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CHANNEL 7 INTERRUPT 
AN OVERVIEW 



Context Switch 
To Scheduler 



c 




Housekeep 



Set Process Clk 
Flag (SKEDF3) 



Oo Context Switching for 
Process Chosen to Run 



Dismiss Interrupt 
(Start Process) 



Dismiss interrupt 





y 



Set Trap to Cause 
Process to Interrupt 
Here When Can 
Reschedule 



Dismiss Interrupt 



Dismiss Interrupt 
(Start Scheduler) 



J 



PI71 



CHANNEL 7 INTERRUPT 




Process Scheduler 
(Entry to Scheduler) 




SCHPR6: 



Plush Cur. Fork 
Dump & Disable Cache 
Wait 2 mi for I/O 

to Stop Before 

Powering Down 



Setup Sched's PDL Ptr 
Update TOOCLK (UPDTCK) 
& Increment Keep-Alive Cm. 



Power Down (2) 




UCLOCK pSCH2 



Update docks 




SCLOAV 



Check 

Load Avs. (1) 



Accumulate 
Sched. Overhead 
Time 



SKC1.K pSCHZ 



Run Null Job 



Update Clks 
& Set Alarm 



TCLKS PSCH2 



Test Clks & 
Perform Actions 
on Timeout 



Clear Process 
Clk Flag 
(SKEOF3I 




SCDRQ1 pSCHO 



Process 
Requests 



SETPSK 



Set Paging 

to Sched 
Context 




SCH1 



CuciociQ 



Compute Increm. 
Run Time & Subt, 
from BSQNT 



Out On 
.dock 



Update FKTLST if nee., 
Job't Run Time, 
Fork's Run Tim*, & 
Tim* Sine* SETRT 



(TINHlx 


v y« 


lncr*m*nt 
(SKEDF3) 










S*t Atirm to Short Cycle Tim*| 
(Mov* 20 MS Into SCKATM, 
Sch*d'l Alarm Clock) I 



Set Bit & TLE Bit in 
Fork's PSI Interrupt 
Word In FKINT 



PSIR4 



Starts th* Fork Up if 
On a Wait List 
Otherwise, Moves it 
to a Higher Run Q. 



Q Return J 



( TCLKS ) 




tneremfint Age 
Sump and Load it 
Into Pager and 
Into FKNR 



( R«turn ) 




Yes 



( SKCLKS ) 



Gat Tim* Interval 
Since Last Update 



OISMSJ 



Dismiss 
Current Job 
(Force SKDJOB) 



SKDLV8 



Do Integrals for SUMNR 
& NRPLQ 

Oo Oev-Oep. Tasks (i.e. Chkl 
for OECNET Messages 
Chk for Chan in TTY Buffer 
Chk Oeleted Pg Qusue 
Chk Forks Waiting for 
Ok Wakeup 

Dismiss Current Process if 
Page I/O Satisfied has 
Occurred 
Reset T1M1 to 20 MS 



Decr e ment Interval 
From 20 MS and 
100 MS Clks 
[TIM1 & TIM2I 



£ 




CLK2 



Dismiss Current Process 
Reset TIM2 to 100 MS 
Check WTLST 
Call Device Dep. Routines 
Whose Timers Have Expired 
Clear QSKED 



( Return ) 



SCH2 



Balance Set Scheduler 

Called to Select Process to Run 



fSKOJOB ) 



SKDJFC: 



Remove All Forks 
From the BALSET 
& Collect All Pgs 
That Are Not Locked 

Clear (SKEDFC) 




TSTBAL pSCHS 



Test 81 Adjust 
Balance Set 
if Necessary 



SKDJ1 




GCCOR pSCH7 



Global 

Garbage 

Collection 



Clear Pg I/O Satisfied 
Flag (PSKEO) 




SCH3 




Get Lin of BALSET 
forks from BSPT Queue 




Compute BALSET Index 
& Gat Fork's Entry in 
BALSET Table 




SK0J3 pSCH4 



Test it 




Get Next Fork on 
BALSET Queue. 
BSPT 



SKDJ2 



SETPPG 


Setup Pager : 


MMAP Entries for 


Cur JS8 & PSB 


inSPT 


Age & Pur Rags 


Clear Hdw Tbl 



Clear BALSET Flags for Fork 

Store Remaining Run Quant. 

into RJQNT & 8S Quant. 

into BSQNT. 

Clear Inerem. Time Kept 

in FKT1 



Put Fork's Q Level & Core No. 
inSJOB0(Loe21) 




WTCHK 



Chk Non-Special 
Waiting Forks 



XCLKS 



Do Periodic Actions 
Call SKCLK pSCH2 
Call SK0LV8 
Call CLK2 



SETOVF: 



Setup Overflow Trio (Op Code 041 ) 
in UPT if User has Enabled for 
Overflow Interrupts 



WTCHK 



Chk Non-Special 
Waiting Forks 



d 



Return 

(to Process Controller 



3> 



AJ8ALS pSCHS 



Adjust Balance Set 



SCH3a 



BKGNOZ: 



Note, Have No Fork 
to Run 
(-1 - FX) 



— c 



Return xo 
Process Controller 



) 
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Test Waiting Baiset Forks 
SK0J3 




Set Up Fork's 
Test Data & 
Call Test Routine 
for Wait Chk 




DISMT3: 



Clear Balance 
Set Wait Flag & 
Deer. NBWT 



Compute Time Waited 
and Add to Total 

Wait in BSWT 




Add Wait Time 
To DRMWT 



Add Wait Time 
To OWRWT 



> 



Add Wait Time 
to DSKWT 



DISMT5: " 



Reduce Fork's BS Hold 
Time, BS Quantum 
& Run Quantum By 
MINIS MS, Actual Wait) 




Load as Much as 
Possible Now 



Return Unrunnable 
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Tin if AJ8ALS 
C TSTBAL ) 



( AJBALS ) 



Clur AJLOON 
Our Running HQ 
and LQ Sumi 



Caiculata Partition Valun 
(Uppar Limits that HO & 
LQ Pagat Can RaachlMI 



Sa»a(SALSHClinlBSHCI> 
InitSUMNRCntto 
(BALSHC) + BSPAO 

(51 




Qw Moid Flag 




Add lt< Rai W« to Accutn. 
Sum Unit, to (BALSCHI ♦ 
BSPAOI 



AJBUGS 



Updata Running No oTForkj 
& No of Pgs tor Ettiwr 
HQ or LQ Surm 



Count BALSET Pork 



Sup to Naxt Fork 




/RtirVSN. 




AJ8SHK 




Shrink It 
So It Doai 


(61 


Fit in BALSET -f 


No 


|"^ v»» 









Cflt. BALSET Fork 
Add WS to Aecum. Sum 
Ramambtr Lan Fork 
in AJBLFK 












AJBUQS 




Sat Holding Flag 


Updata O Suim 











SCHb 
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( AJBAL4 *) 



Ctar "Just Passad Fork 
Not in BALSET"Fla« 



Init GOLST Pointw 



AJ8AI.X: 




Raouea Aecum, Sum 
bv Pari Offtat (BSPAOOI 




If Mom Than 1 Fork in tna 
3ALSET, Ramon the Last 
On* Kapt in th« BALSET 
with Hoist Tim* Uaft. 17) 



Chk for Consisrancv 
in BALSET Sum 
Caieulitad & SUMNR 
(BUGGHK if not OK) 



AJSALY 



Sat Tim* for Hast 

Pariodic Call to 

AJBALS 

Now r 1 Sae. - (NXTAJS1 



Gat Count of Forks 
Loaned this Call 



Q Saturn j 



AJBSHK 



Shrink Fork 
So It Fits 



16) 



SCHSa 
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Yn 




AJBCQS 



Chk if Adding Fork 
Would ExcMd 
Partition Limit 



Sub (Oiff + 2) 
from flm WS and 
from SUMNR 





AJBCQS 



Chk Partition Limit 




Y«J 



AJBAL6; 



LOAOBS 



Lo*d Pork 



AJBL11: 




Nott Just Paiuad 
Fork Not in 
BALSET 



C2u8ALT"^v 
ciSCH5»^-/ 



If a Prtvioui Fork 
Not Loadad. Gi»a 
No Hold Quantum 

I 



Updata Aeeum Sum 
with Fork's WS Siza 



I 



AJBUQO 



Upaata Running 
Sumi 



Count BALS6T Forkj 



SCH6 



AJBAL1 
pSCHSa 
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QCCORX 



tncrem »of GCCOR's 
(NQCCOR) 



GCPC1 



For 1st N Pgs on RPLQ, 
Undo Thtir Ptrs, Flush Their 
Back Ptr», & Oar Their 
CST2 Entries 



GCPC2: 




Compute Needed Pgj 
GCMINP - GCMINO * NRPMIN 
(SI 



Setup PI with NRPLQ + IOIP 
Qui BSHC1 



GCCOR3: 



Situo in P2 Ail the Bit 
Positions for Forks in 
the BALSET 



GCCOR2 



Store P2 Complement (Forks Not 
in BALSET) in PUBCL 



SWPOMI pPF12 



Init Swapout List 



Setup to Scan CSTO 
After Res. Mon./Lait 
Scanned Pg. (in GCCLPG) 



SCH7 



Don't Collect Pq, But 
Continue Scan If More 
Pgs to Look at 
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Collect Page 
GCCS 




OASWSP 



Design Pg 
From Fork 



Get Backup Adr 



GCCQ1: 



lncr«m. 
BSHa 



SWPOUT pPFU 




Do Single Pg 
Swp Out 



Continue Scan 
GCC1 




Step to 

Next Pg 



Remember Last Page 
Done-in GCCLPG 



SWPOMG pPF13 



Oo All Swaps 
Queued Above 



Clear PUBCL&CGFLG 

I 



f Return) 



SCH8 
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( SCDHQ1 ) 




Sdiadular Reguatt 
Proctnor 



C-tOBSBT ) 



Raturtt 



G«t Entry From 
Rag Tbli, SCOROB 
(Data, Oitp Adr) 





Yai 



JOBSR1: ' 



TTEMES 



Gin* Utar 
Bad Mtw 



Anion Job Ne. From 
FREJOB linked Utt 



Prints "Full" 



Clear TTY's 
Entry in TTFORK 

Table 



ASSFK pSCHIO 



Gats 

Fork 



Stora Job No. in 
FKJOS Table 



ASFSB 



Anion * SPT Slot & 
Adjust Shr Count 



SCH9 



Um index for JSB 
Stora SPT Indax for 
JSB in FKJOB Tabla 



J_ 



Stora 

1MEWJ8F FSeo,. TTY Mo. 

in she Psaudo-lntarrupt 

Communications 

Tabla. FKINT 

(Return) 
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Assign Pork Slot 



c 



ASSFK 



Gtt Fork No 
From FREFK 
Linked List 



Sat Up Wait Tast 
Routina for Fork 
In FKSTAT 
(0,. JSKP) 



Sat Up 

FKQTM— Quantum (300ms) 
FKTIME - Tima Fork Put 
on Run Q (T00CLK) 
FKON - Run Q Laval (0) 



WTCONC 



Put on Wait 
Queua (9) 



Sat Flags in LH of FKINT 
(400000 + NEWFKF) 



Clear Entries for Fork in 
Following Fork Tables 

FKINTB, FKPGS, 

FKCNO, FKJOB, 

FKWSP 



Sat Fork's Aga 
Stamp to 100 & 
Reserve Working 
Set to 3 



Call AS FSB Three Times 
to Obtain Three SPT Slots, 
Each with Their Share 
Count Updated. The Slots 
are for the Fork's PSS. & 
UPTA Tables. 

1 ■ 

( Return ) 



SCHIO 
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Scheduler Comments 
SCHEDO ; 

(1) Running averages, exponentially weighed over intervals 
of 1, 5, and 15 minutes /are maintained for the number 
of runnable processes overall, as well as for those in 
High Run Queues and those in the Low Run Queues. 

(2) Final phase of powerdown seq. clears the priority 
interrupt system and causes the system to loop in the 
ACs until power actually vanishes. If the power fail 
interrupt was spurious, the loop will time out after a 
few seconds and the system will be continued at 
address SYSRST. 

(3) A very limited set of central functions for debugging 
purposes has been built into the Scheduler. To invoke 

a function, the appropriate bit or bits are set into loc 20 
(SCTLW) via MDDT. The word is scanned from left to 
right ( JFFO) ; the first bit found set on the scan 
selects the function. 

Bit Causes the scheduler to dismiss the 

•current process and to stop timesharing. 
Useful to effect a clean manual transfer 
to Exec-mode DDT. System may be resumed 
at SCHEDO if no IOB reset is done. 

Bit 1 Causes job specified by (20) «« to be run 
exclusively . 

Bit 2 Forces running of Job back-up function 
before halting the system. 

If loc 30 (SHLTW) is set not equal to jS , the system 
will crash. (Same as setting bit 2 of SCTLW word.) 
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AJBALS 

(4) Upper Limit for LQ=MAXNR-MIN [Max HQ Reserve, HQ Load Avg.* (16)] 
Upper Limit for HQ-MAXNR-MIN [Max LQ Reserve, No. of LQ forks * (32 

(5) SUMNR reflects the number of timesharing pages in use. Its value 
after AJBALS equals the number of pages reserved for balance set 
members plus BALSHC (the number of pages shared, but not owned, by' 
balance set members plus the number of locked pages) „ 

BSPAD reflects the number of pages set aside for balance set member; 
as their working set reserves grow. The real value of BSPAD is 
offset by a factor of BSPADO. When forks are trying to stay in the 
balance set, the adjustment algorithm allows the pad offset to be 
subtracted from the accumulated sum before it checks if the fork 
can fit. 

i.e., n 

(BSPAD +S Res, WS ) - BSPADO + Res. WS > MAXNR 

i-1 i n+1 "" 

The adjustment algorithm does the opposite (i.e., adds the BS-PADO - * 1 * 
factor) for forks trying to get into the balance set. The overall 
affect of this is to ensure (as much as possible) a certain number 
of pages be available for balance set forks. 

(5) The shrink algorithm shrinks the fork's reserve working set by: 

MIN [Reserve WS - Current WS, Accum. Sum + Fork's Res WS-MAXNR] 

Notice that the fork's reserve working set will not be reduced 
below its current working set. 

(7) This is the rare case of forks, with hold-time left, expanding. 

The lowest priority one is removed. If there is only one fork in 

the balance set, it is not removed. (Note: it is possible for one 

fork to be greater than MAXMR due to the BALSHC count changing) . 

GCCOR 

( 3 ) If it is a forced clear, then GCMINO is made very large so all of 
core will be collected. However, its usual value is much lower. 
(Currently 54 decimal) . 
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zkSSFK 

(9) The fork is actually placed on the GOLST at this time. WTCONC, 
after putting a fork on WTLST, checks if the wait condition is 
satisfied. The test routine-, JSKP, gives a skip return indi- 
cating that the wait is satisfied. This causes UNBLK1 to be 
called which in turn calls. SCHEDJ to unblock the fork and to 
requeue it from the WTLST to the GOLST. 
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PAGE FAULT HANDLING FLOWCHARTS 

PGRTRP - Performs the Principal Accounting, Analysis, PF1 
and Resolution of Page Faults 

PGTACC - Accounts for Page Traps PF2 

XGC - Local Garbage Collection PF4 

SWPOUT - Swapping Out a Page PF14 

NICCKS - Check In-Core Size Limits PF3 

GETTPD - Determine Cause of Trap PF5 

NIC - Not in Core Trap PF6 

SWPINW - Swap In and Wait PF10 

SWPIN - Swap In a Page PF11 

WCPY - Write Copy Trap - PF8 

ILRD - Illegal Read Trap PF7 

ILWR - Illegal Write Trap PF7 

TRPO - Age < 100 Trap PF9 
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Enter Mart on Pg Fault 



PGRTRP 




Sat Mon. AC 81k 
& NOINT 



(^J»GRTS^) 



Get Flags, PC from 
TRAPFL, TRAPPC & 
Store on Stack 



Store PC 
in lUPOlt 




Save ACP 
Setup Trap Stk Ptr 
(TRAPSPI - P 
Inerem Trap Cntr. 
♦1 -UTRPCT 



SUGHLT if Ref. 
Invalid Section 



NOSKED for 
Duration of Trap 



If Pg Trap Time Flag 
(IPTIMI if Set. Oo Not 
Charge P.P. Handling 
to Fork's Run Time 



Init Time Interval of 
Trap Code unlets 
Already Initialized 
lie. Nested Trap) 



Save ACs 1-4.7.CX 
and ITRAPSWI on 
Stk Adr+(8HC*1I 



Oispatch to Err. Handler 

PGRTH: Pa Tb Pantv/Refill Error 

ILRD: Proprietary 

AORCMP: Address Compare 

ILSCN: Illegal Section 

ILIND: mean Indirect 



If Not Recoverable. 
Handle at Hies. Ref. 
Otherwise, Retry 



PGUNTP 



), 



Retry 
Recoverable 



pPFIe 




—i . Pg or Pg Tot Not «n Core 

NIC ) (pPF6l 



TRPO ) ft or ^ Tbl *»••"■ '00 

— — — ' (nPF9t 

{ NPG ") ;Null Ptr (pPF8l 

WCPY ) ;Write Copy (pPFSI 
LVVR ) ^Illegal Write (pPP71 



;lllea. Ref. Due to Dismounted OFN 
(pPF7> 
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Page OK to Ref. 



( PGUNTP ) 



If 1st Trap & Including 
Pg Trap Tima, Read Current 
Time to Complete Timing 
of Trap Code & Update 
PTTIM. HSPTTM, SPTTIM 




Flags, PC - FFL. FPC 
-1 - TRAPC 
OKSKED 
-1 - INTDF 



Restore Flags, PC to 
TRAPFL, TRAPPC & ACs 
1-4,7, CX & TRAPSW 
from Stack 
Restore P if Outer Trap 



GOUSR: 



Setup User AC BIK 
as current 81k 



OKSKED 
OKINT 



c 



Return 

XJRSTOFFL 



) 



Q 



Return 

XJRST @ TRAPFL 



) 



PF1d 
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Account for one Pg Trip 




C=3 



XGC pPF4 



Local Garbage Collect 



Update lnterfau!t Av 

A* » (C x Av + Time)/C + 1 



I 



Get Subsystem Index 
(if any for job) and 
account for Pg fault 




Yes 



Get Difference between 
Age at Ian XGC and 
Current Age (Adjust for 
wrap around if nee.) 



Reduce Reserve WS 
and SUMNR by X 
X-flesWS-ICurWS + 4) 




No 



NICM6I 



=^p 



NICCKS aPF3 



Cheek for 
Allowable Size 



Calculate Ratio of Actual 
Interfault Avg to Desired 
(Desired ■ 2 x Avg Swp Lat) 




Set Bit for Faulted 
Pg in the Fork's WS 
Bit Table in the PSB 




Ret 



Increase Window Size (CAPT) 

(CAPT) + (CAPT) - (CAPT) 

16 



No 



Reduce Window Size (CAPT) 

(CAPT) - (CAPT) - (CAPT) 

16 



See if CAPT within Limits 

If > CAPTMX. Set CAPT to CAPTMX 

If < CAPTMN, Set CAPT to CAPTWIN 



Set CAPT to Fixed 
Window Size (3 Sec) 




PF2 
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Chaek Ov«rall Sizt for 
Physical Cor* Limit 




Yas 



-> C »ET ) 



5E3S 



Init Tamp Window Siz* tci 
7( CAPT ) for Possibia XGC 
8 



Reduce Tamp 
—\ Window by C APT 

" 2 




Sat Ra* WS ■ Cur WS + 1 

Updata SUMNR (BALSET TOTAL) 




No 



Sat up Schad Test 
for BALSET Size 
NICTST - ACI 
RDISMS 

( Ratum J 



PF3 
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Local Garbage Collection 






XGC ) 



XGC3 



Setup to Scan 


CSTO Beyond Ret Mon 


Compute Max No. of Pgs For 


To Collect (All of Pgs For 


Procesi in Core) 


Calculate Cutoff Ape 




PGRCLD 



Clear Hdw. Pg Tbl. 



XGC2: 



Get Age Field of Entry 
in CSTO 



Setup to do 

Housekeeping for 

the Fork's Working Set 




XGCS: 



If Pg Ret. by Other Fork 
Age Invalid, so 
Set to Cur Age 




DASWSP 



Oeassign Pg From Procesi 
Deer. WSP 
Release Core No. if . 

WSP - 
Mark Pg Unassigned 

in CSTOFK 



SWPOUT pPF14 



Swap it Out 



Increment Pg No. _ 
For CSTO SCAN] No 




For Each Pg in the Fork's WS . 

Clear its bit in the WS Bit Tbi (in PS8) 

if the Pg is: 

Deleted. Not in Core, or Unessigned ■ 
in CSTO (Unless Rd. Compl.) 

If the Pg is Rd. Complete, Call AGESN 

te Assign the Pg & Set the Age 



GElED 



pF4 
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Construct 
Idamitv 
ofPg 
Pointed to 



Datarmina Causa of Trap 
( GETTPcT) 



Get ?g Fail Word 
From TRAPSW 



FPTA 



Gat Idant 
of 1st Ptr 



GETTP1: 



T 



Gat PT Idant 




Gat Idant of Pg 
From SPT- 



CHKDMO 



Chk for Dismounted 
OFN 



CHKDMO 



CHK for 
Dismounted OFN 




GETT1F: 



Stora Err, PMAPX7 
in LSTERR 



Gat Adrof PT 



Gat Oisp Adr 
ILRO 



■a^/^RaturnJ 



GETT1A: 



Gat Oisp Adr 
NIC 





->—■( Raturn ) 



Gat Oiip Adr 
PGUNTP 



,-LL 

(Return) 



GETTIO: 



Ptr Word ^N, 
dicate Copy 


-^Ya7 


Gat Oi<p Adr 
WCPY 






on Writa y 


' 




| No 


G 


ETT1E: 


1 


Writa ^S 

Lteal ^ 


'Ha 


Gat Oiip Adr 
ILWR 


-»-^ Rat 


urn 
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( "' c ) 

NIC2: f 



GETTPD pPF5 




Hindi* 
Othar Caw* 



") 



CHKRPQ pPF9a 



Maka Sura 

Thara it Enough Pat 

on tht RPLQ 




Whan 
W» \Ra*ehad 

"Hurt 
sEfMUflh? /No 



SWPINW oPFlO 



Swpln 

P9 



Mun Sm if (3) 

Writt is Pooibl* 
Rachk Aochi & If 
Can't, than 90 to iLRO 



NIC82: 



GalPTN 




Hava 
Ona? 



Yas 



No 



Gat Cora Adr & 
Lock it in CST1 
in Cm Raikad 
Baiow 
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QCHK 



Chk for Enough 
Oiik Spaca for 
Pg Creation 




ILRF 
pPF? 



J 



No Room 




Sat up Schad Tail 
Blk until Unloekad 
ACI/OFNUCT 
MOISMS 



Sat OFN Lock & OFN 
Modif lad in SPTH 



I 



Whan Raschad 



( " 1C ) 



FNDLDA 



Find Last Disk Addrau 
Anignad in this X8 



Gat OFN & Pan 

Str No. to OSKASN 



OSKASN 



Ankjn Otk 
Adr for Fila 
PB 



Gat OFN & Subtr. 
1 from Quota Tbl. 




Stora Naw Addr in 
Indax Blk 



Stora Naw Addr 
inSPT 



NICB3: 



I 



Unlock Indax 
31k in Cora 



Unlock OFN 



PF6 
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Illegal Writ* 

C "- WR ) 



Illegal Reference Traps 
( "- RD ) 



CJ*T> 



Set Error Cad* 

I LLXOI - LSTERR 



Store Trap Status Word 
in UTRSW in PS8 
(In Case Usar Wants it) 



f^BUGHLT 



Y*s 



Y*s 





II.WRI: 



Sat Error Coda 
ILLX02 - LISTER R 



Q^ED 



ILRFU: 



Post Interrupt 



Simulate PUSHJ by 

Updating PDLPtr 

(BHC *1) + (TRAP API - (TRAPAP) 

and Saving Instr Trap Adr +■ 2 

(Rat Adr) on The Updated Stk. (5) 



L 



ILRFI: 



3 



Gat Adr to Transfer to 
from Word Following the 
Instr Causing the Trap 



Alter Return Adr Stored on 
Stack Pointed to by AC P 
by Storing Adr to Transf to 



Q 



PGUNTP pPFIa 



) 



Save Int Cod* (.ICIROI 
on Stack 



ITRSIM 



Check for ERJMP 
or ERCAL 




•ILRFX 



Altar Rat Adr 
With Adr Gotten 
from ITRSIM 
Routine and 
Prune POL Ptr 
(Subt. BHC + 1 1 



K PGUNTP N 



PSIRQO 



Request 
Interrupt 
for This Fork 



Gat it Seen 
by Executing 
CHKINT Macro 
(it AOS SKEDF3 
ISBSCOCHN) 




Incre. Ret Adr 
Stored on Stack 
(Skp over Instr 
Causing Trap) 



f»F7 
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Copy On Write Trap 
( WCPY ) 



Clear Write Ref Bit 
in Pg Failure Word 
(TRAPSW) 



GETTPD pPF5 



See if Pg Readable 




Get Adr of Source Pg 
& Lock it in CST 1 




SETSPG 



Mep The PT in 
The Monitor Map 



Get Ptr & Modify Ptr 
Type to Immed. With 
Select Access Sits & 
'Copy' Adr and Store 
in Pg Tbl 



Put Original Ptr in 
CPYPG in PSB 



RELSPG 



Release Monitor Map Slot 



Reference Souree Pg, 
CPYPGA, to Ensure Access 



SWPINP 



NOSKEO 

CALL SWPtNW pPF10 
OKSKED 
Will Copy from CPYPG 

to New Page 



Handle Other 
Case 



■ ^buqhlt) 



) 



Unlock Source Pg in CST 1 



MRPT 



Get Idem of 

Shared Pg Being Released 
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Pg Not in Existence Trap 



TLRF ^\ 
pPF7 J 




Set err Code & 
Reg lnt..iCNXP 



PS1REQ 



PSI Ref. 



Get Int Seen 

With CHKINT Macro 

(nicppfsj 



3 



PF8a 
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Pg or Pg Tble 
Age < 100 Trap 



C TRPO ") 




Dispatch to On* of 
The Following Based 
On Age Fiaid 



Start Trap 0»er 
Pg Probably Hal 
Computed Writing 



On RPLQ 

or Writa in Progress 





Rd in Progress 



CHKRPQ pPF9a 



Maka Sura Enough 
Pagaj on RPLQ 




TRPSPM: 



Sat Up Schad Tan . 
ACT /Aga Field.. SWPRT 
ROISMS 



Wait for Pg 



AGESN 



Assign Aga 



NOSKED 



(PGUNTP A 
pPFIa J 



Untrap & Continue 




TRPSPI: 



SKPNWR pPF9a 



Skp If No Writes in 
Progress On Core Pg. 
Otherwise Reschedule 
Until Writa Complete 




Recheck Trap 



RPCST 



Remove Pg 
From CST 



QNSPMQ 



Place On 
SPMO 



(PGUNTP ^ 
JED 



Untrap & 
Try Again 
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( chkrpq) 



^skpnwr) 




Set Up Sched Ten 

AC1/<NRPMX)„TRP0CT 

ROISMS 



NOSKED 



I 



f Return ) 



Increment Global Garbage 
Collection Flag (CGFLG) 



( Return ) 



unsuccessful 




Ret Skp \ 



increment DWRCFL Flag 
(Says Fork Waiting for 
Write Completion) 



Sat up Schedule Test 
ACI/Core Pg No... DWRTST 
ROISMS 



NOSKED 




(Return) 



Yes 



m-( Ret Skp ) 



Successful 



PF9a 
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REQUESTING DRUM OR DISK READ 
(PAGEM LEVEL) 



Swap In & Wait 
for Completion 



C 



SWPINW J 
| (6) 



Count Swaps 
Increm USWPCT 



SWPINpPFII 



Swap in & Wait 
for Completion 




AGESN 



Fix Age on Pg 



Lock Pg in 
CST1 " 



SWPIW4: 



E 



I Get Original 
OFN„ PN 



SWPINpPFII 



Swap the 
OrigPg 



Unlock PT Pg 
In CST1 



SWPIW1 : 



PGSWT 



Chks If Pg State Code 
Says Read In Progress 
and RDISMS if so 



{ Return j 



SWPIW3: 



NOSKED 



SWPIN pPFII 



Swap in PT 



OKSKEO 
Lock Pg in CST1 
Wait to Finish 
With POISMS 



AGESN 



Assign Pg 
an Age 
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REQUESTING DRUM OR DISK READ (Continued) 
(PAGEM LEVEL) 



("sWPIN ) 



Swap in Page 




When Reached 



Decrement NRPLQ & 
Remove Pg From 
Replacement Q (Linked 
List in CST3) (6) 



SWPQT: 



-*■> 



Set up Sched Test 
SWPWTT - ACT 
POISMS 



aear CSTO & CST3 
Entries for the Pg 



■depg 



Reset Previous 
Ownership 




SWPI3 



Get Owning 
PTOFN 



SETSPG 



Map PT Through 
Monitor Map 



T 



Lock PT in Core 
(BUGHLT if Pg in Pg 
To Air end y in Core) 



Store New Core 
Adr for Pg in PT 



RELSPG 



Release Slot in 
Monitor Map 



No, SPT 



BUGHLT 
If Adr From 
SPT In Core 



Store New Core 
Adr (Pg From 
Repl. Q) in 
SPT Slot 
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Store Old Adr in CST1 

(Backup Adrl 
Store Loc of Owning 

PT in CST2 




Clear All Words in 
New Pg from RPLQ 



Copy Old Pg (Adr 
Saved in PSB's 
CPYPG1 into New Pg 



"F 



Sat Age Field To Read 
Complete, Set Modify 
Bit. & Store Owning 
Fork Index 



Return with Approp. 
Sched Test. 
Pg No.,. SWPRT 



-•W 



( Return ) 



SWVPZPG 



Zero Pg in 
Core 




(BUGHLT) 



Set ftg State Code 
to Read Complete 



DSKIO pPHY1 



Initiate Diik 
Read 



Increm DRMRO 



Inerem DSKRO 



Return with Approp. 

Sched Test. 

(Pg No... SWPRT! 



Return Approp. Sched 
Test. (Pg. No... DSKRT) 




SWP1X 



Return 



PF11a 
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MULTIPLE PAGE SWAP OUT ROUTINE 

SWPOMI - Init List 

SWPOMI. • Called to Add Page to Swap Out List if Possible 

SWPOMG- To Begin I/O for All Pages on Swap Out List 

SWPOUT - Initiate Swap Out of Single Page 



Add Pg to Swap Out List if Possible 

(swpoml) 




Init Swap Out List 

( swpqmT) 



Clear 
(SWPRCOI 



T 



Init End Ptr 
SWPLST-(SWPLSI) 



Init List Ptr 
- (SWPLST) 



CjED 



Pg Can't be Written on Drum 
or has no Drum Address 



GDSTX 



GetDST 
Index for 
Drum Addr 



Get Adr of Pg 
On Drum & if 
Modified bit is 
Set, Set Modified 
Bit in CSTO Entry 



Clear OST Entry & 
Put its Porrrurr Contents 
Into CST1 



DASDRM 



Deassign 
Drum Addr 



Put Pg Want 
to Swap Out 
on End of 
Swap Out List 



increment Count 
of Pgs on List 
(SWPRCOI 



Ret 
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Assign Ntw Drum Storage & 
Initiate I/O for All Pages on 
SWPOUT U« 








Clear Modified Bit (If 
of Page in CSTO Entry 



Get Lilt of Pgj To Oo 
Get Count of Pgs Left 
on Liit 



Set) i 

: I 



DRMAM 



Try to Get 
Specified No. 
of Sequential 
Pages 



Remember First 
Adr of Group 



Remember Count 
of Pgs in Get 




Get Drum Adr 
inSeq. 



ORMASA 



Assign 

Adr on Oram 



Store Drum Adr 
in CST1 Entry 
for Page & Former 
Contents of CST1 
(Disk Adr) into OST 
Entry for the Oram 
Address. Marking the 
Modified Bit (BWR8IT) 
if Pg to be Swapped Was 
Modified in Core. 




Store Write-in-Progress Code 
in Age Field in CSTO 



Increment Writes in Progress (IOIPI 
and Oram Writers (ORMWR) 



3 



ORMIAO 



Bump Oram Adr to 
Next Page 




SWPOG3 



Get Ptr to Next Gp.. Tie Off 
Current List Si Set Up Next 
List 



Get Current List 
& Set Write Flag 



ORMIOM 



Oo Muitipage Write 
(Calls ORMIO pf>HY1 
for Sash Pg„) 
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" SWPOUT ) 



Hera to Atiign 
Drum Adr 





Sat Orum Adr » 
Ntw Adr in CST1 & 
Put Former Adr. in 

OST 




Cl«ir Mod Sit & Store 
PSWIP Coda in CSTO 
Entry 



Increm. Writes in ProgreM 
(IOIPI 
Set Writ* Req. 



DBMIO pPHY1 



Initiate Orum 
Writ* 



Incnm. ORMWfl 

"ixr 

(Return) 



<aw( Return j 



PP14 



42 




Gat Backup Adr 
from CST1 



BKUP7: 



BUGHLT) 




LNo, Drum 



QDSTX 



Gat DST tndtx 



Get Naxt Leva) 
Bkup Adr from OST 




Ralaaia OST Slot 

(Satto-1)& 

Put Format Contants 

of OST Slot into 

CST1 Entry 






Oaar Modify 
Bit in CSTO 
Entry 


OR.UK 


ra: 








OFRQ 




Put Pgon 
Top of 
RPLQ 




* 






Raquast Writt 
Incram DSKWR 
&IOIP 














t 








Clair DSKNB Bit 
in CST1 Entry if Sat 






t 






Sat Writa-in-Progress 
(PSWIP) in Aga Piald 
of CSTO 








♦ 








DSKIO pPHY1 








Raquani I/O 
to Disk 






i. 




*" 






( Rat urn ) 





OASDRM 



Daauign 
Drum Adr. 



PF15 
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Page Fault Handling Comments 



PGTACC 
(1) 



NICCKS 



OETTPD 



MIC 



Checks if process has accrued more than or equal to 
the number of age ticks of GCRATE. Currently, this 

which implies 2 sec. of process 
(i.e., the age stamp is incremented 
process run time) . 



is set to 50, 
virtual time 
every 40 ms of 



(1) GNPBAS is currently initialized at system startup to 
zero and is incremented/decremented only when pages 
are locked/unlocked. It is currently only tested by 
NICCKS as well. 



(2) The age field when used to hold the age stamp, will 
always, have a value of 100. or greater. This checks 
if any of the lefthand 5 bits of the age field are 
set. 



(3) Could take the ILRD path, for example, when OPENed 
file for write, but PMAPed for each of a nonexistent 
page. A page would have 'to be created which would 
then imply a write which was not enabled under PMAP. 

(4) If file page faulted does not have its own SPT slot, 
- but has to be mapped (using indirect pointer) via 

- the index blk slot in the OFN area, then the index 

blk will be locked in 
case of reschedule.) 



core. (So can't be swapped in 



(5) Note in the predispatch code that AC1 
BHC + 1 and AC, P, which holds a 
pointer, was saved in TPAPAP. 



was stored in 
push down list 
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SWPINW 



(3) SWPINW will invoke SWPIN to swap in a page into a 
page from the RPLQ. However, this same code can 
also be entered with different flag settings and be 
used to swap in a page into a page from the special 
memory queue (SPMQ) , a queue used by the memory 
"error handling code. 



SWPOUT 

(7) SWPOUO is called from: 

SWPOTO which clears the SWPKPF bit (for top of 
RPLQ) before calling SWPOUO and 

SWPOTK (called from the UPDPGS JSYS) which sets 
the SWPKPF bit (for end of RPLQ) before 
calling SWPOUO. 
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JSYS CALL FLOWCHARTS 
DEVICE INDEPENDENT LEVEL 



GTJFN - 
OPENF - 
SIN/SINR- 



Get a JFN 
Open a File 
Sequential Input 



3YTINA - Call Device Dependent Code 
to Get a Byte 

SI0R2 - String I/O Multiple Byte 
Transfer 

SOUT/SOUTR - Sequential Output 

BYTOUA - Send Byte to a Service Routine 

Pmap - Map a File or Fork 

! JFPGS - Update File Pages 

CLOSF - Close a File 



GJ1 
OP1 
SI 

S2 
S3 
S4 
PM1 

UD1 

CL1 
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GTJFN JSYS 




Assign First Free 
JFN Bloek in JSB 
(This Determines JFN =1 



No 




— (ERRGJFX3) 



Parse User Arguments 
Fitid By Field. Default 
the Argument! Not 
Specified if Have Legal 
Default 



(II 




No 



-— ( error"*) 



Store Argument 
in JFN Slock 




Cleanup Temporary 
Cells Uied by 
GTJFN 



Setup of Flags or 
Indexable File Handle 
to Give to User 




No 



GETFDB 



Address of FOB - FILFU8 
(May Have to Create FOB 
for New File) (3) 



^ Return ) 



GJ1 



Setup User 
AC! with 
JFN 



T 



(^ Rtturnj 
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.OPENF 



OPENFJSYS 



CHKJFN 



Check JFN 
Validity. S«t 
Sutuj Bits 




Enor ) 




PMAP JSYS 



PMAPO 



Call This 
Routine for 
AH Pagtt 



PMAPO 



Call This 
Routing 
for Pgs up 
to the Pg 
This 
Boundary 



Destination is a Fork 
PMAP2 



Increment 
Cnt of Pgs 

Mapped in 



Return 



( PMAPO ) 



Reduce Map 
Count in JFN 
BlklFIULFW) 
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SIN/SINR JSYS 



Set Flag to 
Sty SIN JSYS 



If Thii i* Special 
Byte Ptr (-1 in UH) 
Create Equivalent 
Regular Byta Ptr. (1 ) 



aU j'NO-D-— -^ 




Sat Flag to 
Say SINR JSYS 



CHKJFN 



ChkJFN 
Validity & Sat 
Up Statu* Flag* 




Return to 
User 



SIOR2 pS2 



Setup & Do 
Byte Blk Xfer 
(41 



Res. Size Longer 
Than User's Hequest 




ST 
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SINTTY 




SIN/SINR JSYS (continued) 



JFNID(OEV'OTB) 



Init JPN for 
Input 



SINTT1: 



SYTINA pS2 



Read a Byte 
From Source 




) 



Unlock and 

MDISMS 

with Sched Test 

From 0*1 Routine 



Whan Resched. 



SINO 



Put Bvtt 
in (Joe's 
Adr. Space 



SIONXT 



Chk if "End 
of String" 
Char 





SIN1 




BYTINA pS2 



Gat Byte 
from Source 




SINO 



Put Byte 
in User's 
Adr. Space 



SIONXT 




; ** Iv«» 


UNLCKF 


Unlock Pile 


.♦ 


( Return ~\ 
V to User J 



SI a 
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Call Device Dap. Coda to 
Gat a Byta 

f BYTINA J 



( BYTINX J 



is Have*" 
^Errors StxyS' Yes 



BYTINX 




Return J 

Unsuccessful 
Raturn 



RETSKP ) 
with Byta 




-— -(err-ioxs) 



Yes 



■{ERR-IOX4) 



BUGCHK if BLKF Rag 
Sat. (Should Only 8a 
Sat by Coda Ahaad) 



8IND(0EV*DTBt 



Dispatch Through 
DEVDTB Tabla to 
Oavica Oapandant 
Coda 



Discard Una 4 Byta 



String Input/Output Multiple Byta Xfar 
( SIOR? J 



c 



Rat 



Sat Up Counts & ptrs 
for transfer 



I 



Successful 
Raturn 




Yas 



— \ Raturn ) 

with Sched Test 
to Caller 



Yes 



■(Err-IOX5 ) 



Yes 



-— (ERR-IOX4) 



CHKTRM: 



BYTBtT 



Do the 
Transfer 



Update FILCNT& FILBYN 



Chk for Line =s 

Si Terminator 

Transfers Byte One at a Time, 

Until Terminator Found or 

FILCNT (Buffer PgCrit) or 

User Count Exhausted 





Transfer Byte to User 
Until Page Cnt (Buffer 
or Window) or User 
Count is Exhausted 
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SOUT/SOUTR JSYS 



SOUT 




Sat Flag to Remem- 
ber Doing a SOUT 



If Using! -1, Addrt 
Special Byte Ptr, 
Change to 7- Bit 
Byte Ptr. 








Set Flag to Remem- 
ber Doing a SOUTR 









SOUTO: 



CHKJFN 



Chk JFN Validity 
(Err Ret if Not OK) 
Setup JFN Status 



SOUTTY 



( ERR-IOX2) 




JFNODIDEVDTBI 



Init JFN for Output 



SOUTT1: 



SOUTB pS4 



Sand Byte 
Through De«. 
Dep. Code 



SOUBYT: 



SIOR2 pS2 



Setup Si 
Do Byte 31k 
Transfer (4) 




Update User ACS 



APPNUL 



Append NULL 



■^Return to User j 



JFNOOIDEV'DTBI 



Init JFN for 
Output 




SOUT1: 



Not End of String 



SOUTB pS4 



Call Device 
Dep Code to 
Write Out the 
Record 



SIOR2 



Setup & Do 
Byte Transfer 
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(^ Return to User 




Yes 



Update Usar AC2 Byte Ptr 
Update FILBYT 



UNLCKF 



UNLDIS 



Unlock & 
DISMS 



UNLCKF 



Unlock the 
JFN 




Yes 



RECOUTIDEV'DTB* 



Call Dev Dep Code 
to do a Record Out 
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( SOUTB ) 



(bVTOUA ) 



8YTOUA 



Send Byte to 
Service RoutitM 





BUGCHKifBIKF Flag 
Set (Should Only B* 
Sat By Dev 0«p Code) 



BOUD(DEV'OTB) 



Call Dev D«p. 
Coda Through 
Dispatch Table 



SIONXT 



Chkfor 
End of 
String 




Zero AC1 



( RETSKP ) 



( RETURN) 



MDISMS 
with Schad 
Tan Routine 
From Service 
Routine 



~r~ 

[ Return ) 




S4 
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Updit* Fill P,g. a 
Cauia Chingid Pagtd 
to bt WriCTan to Oltfc 



Ym 



UFPGS JSYS/ODMP 



UPGS7 



fSitUfnJ 



SETMPG 



Map Indax 81k 
in PS8 Slot 



Sat up to Do 

Requanad Pg» in 
This Indax 31k 



Sat Pan 2 
Flag & Set up 
& Oo All Pg> 
Again 



SETMG 



Raiaase 
Indax 81k 
from Map 



Ratum 




Gat Ptr to Pg 



UPGS4 ) 





SWPINW pPFlO 



Swap in 
Pg & Wait 



SKPNWR 



Chaek if Writa 
in Program. 
ROISMS if so. 



Ytt. Raehaek Pg 




AGESET 



Assign Pag* 



SWPOTK 



Sat SWPKPF » 1 
Call SWPOUOtpPF 14 
to Swap Out tha Pg 



UD1 









i 




P9^S 


Raquan Swap to 
Disk. Sat DSKSWB 
Bit in CST3 Entry 




Uoeked 


^ No 


T Yw 
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CLOSF JSYS 



Ym 




CLZF pCL2 



DoCtoM 



CL2ALL 



Does a CLZF F 
JSYS for .FHSLF 
(Fork Issuing Call) 



■{ Return ) 




»-( £rr-R8t"*) 



CL1 
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C cm* ) 




-(ERR-CLSxT) 



CHKJFD 



If JFN Chk 
Not OK. Err Ret 



CEED 




CLSX1 



Call Device Oep Cod* 
CLOSDIDEV'DTB 





Whan 
Unblkcd 


UNLOIS 




Does MDISMS 




with R 
toBlk 


mors 


Yes 




Assign Pg 
Map Cnt to 
that JFN (2) 



UNLKF 



Unlock file 



UNLKF 



Unlock file 



No * ~ Tf 

( ERR-CLSX3") 



■^ Return) 



CL2 
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GTJFN Comments 

(1) This code is looking for a file specification of the forms 

Dev: Directory Name, type, gen ;T( temporary) ;P (protection) ; A (account 

One or more fields can be defined by logical names. 
If any fields are omitted from the specification, the 
system will default the values as follows; 

Device DSK: 

Directory Connected directory 
Name No default for disk 

Null for other devices 
Generation Highest existing for input 

Next highest for output 
Protection As specified for directory or 

protection of next lower generation 
Account Current user account 

(2) The internal GTJFN code uses several locations in the 
JFN block as temporary cells. These locations have two 
names in the JFN block table descriptions. The JFN 
block storage locations set up or used by GTJFN are: 

FILLCK* FILDDN FILNEN 

FILTMP* FILPRT FILVER 

FILACT* FILSTS1 FILCOD (LH) 

FILOPT* FILLNM* 

FILDEV FILDNM 

*Used internally only by the GTJFN JSYS. 

(3) The creation process of the FDB simply asks for space 
in the directory for the FDB. 
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.OPENF Comments 



(1) Cell FILDEV in the JFN blk has the device dispatch 
table address. For example, for disk, GTJFN sets 
the dispatch table address to DSKDTB. If spooling 
to disk, GTJFN sets the dispatch table address to 
SPLDTB, but the OPENF code changes the dispatch 
table address to DSKDTB and sets up a file 
specification in the JFN block. 



.SIN/.SOUT Comments 



(1) TOPS-20 allows a user to specify a special byte pointer 
of -1,, Address which is interpreted as a 7-bit byte 
size beginning on the word boundary, Address. 

(2) A user can do I/O from one place to another in core by 
specifying byte pointers for both source and destination, 
This differs from BLT in that the use can transfer 

on non-word boundaries. 

(3) For disk files, FILCNT will be the number of bytes 
remaining in the window page. For magtape and other 
devices it will be the number of bytes remaining in 
the current page of the buffer. 

( 4 ) The routine BYTBLT only moves data up to the page 
boundary of the current buffer page. 

(5) If the user has not specified 0F1PLN in the OPENF, 
line numbers are stripped off the beginning of each 
line. (See SIN JSYS in Monitor Calls manual for 
definition of terminator.) 
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.PMAP Comments 



(1) A page is private if it is not shared between a 
file and a fork. 
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UPDPGS Comments 

(1) Routine scans page table twice: first. time to request 
writes on all changed pages. Second time to wait for 
completion of writes. (This is faster than waiting 
for each write to complete as it is requested.) 

(2) If page has not been modified,, a check is made to see 
if the drum is full and if so, to release this page 
back to the drum. The map pointer to the page will be 
changed to its disk address. 
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CLOSF Comments 



(1) If user has switched primary I/O to some other JFN 
and attempts to close it, an error results. 

(2) The page map count in PILFW reflects the number of 
pages mapped and a CLOSF can't be done on a file if this 
count is greater than . 
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JSYS CALL FLOWCHARTS 

DSK DEPENDENT LEVEL 



DSKOFN - Disk Opening of a File ODl 

ASFOFN - Assign OFN OD2 

UPDOFN - Update OFN ODl 

DSKSQI/O -Disk Sequential Input/Output SD1 

NEWWND - New Window Page (Next Page of File) SD2 

DSKCLZ - Disk Closing of a File CD1 

RELOFN - Release OFN CD2 

DASOFN - Deassign OFN CDS 

MOVDSK - Move Page Back to Disk . CD3 
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Disk Dev Oep Code 
Called From Table Slot 
OPENO (DSKDTB) 



OPENF-DISK 
Oev Dep Code 




Error 



OPENF3: 



1 



Update Date Time Info 
in FOB. Update Last 
Writer If Writing. 



If Superceding (i.e. Opened 
for Write Only to an 
Existing File). Delete File 
and Mark File as New 



Incr. OFN Cnt. in S08 




♦ 






GETLEM 






SetupFILLENfrom 
OFNLEN Table 






f Return J 





OPENF9 




Yes 



DSKASN 



Assign Disk Space 
for Index Blk 



UPOBTB 



Update Bit 
Table 



Translate OPENF Access Bits 
to OFN Bits for SPTH 
Comparison or Storage 
if New OFN (1) 




OPNLNG: 



ASFOFN p002 



Assign OFN for 
Super Index Blk 
If Error, Err Return 



ASFOFN pO02 



Assign OFN for 

Index Block 

If Err, Err Return 



Store OFN in 
RH of FILOFN 



Store OFN in 
LH of FILOFN 



ASFOFN pOD2 



Assign OFN for 

Index Block 

If Error, Err Return 



UPOOFN pCOS 



Write XB on Disk 
(if Opened New File 
With Thawed Access) 



£ 



Store OFN in LH of 
FILOFN and RHof 
FILCOD (2) 



OD1 
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Assign OFN 

(asfofn ) 



OPENF - DISK (Cont) 




BUGHLT ) 
Str.8ad 



ASOFC 



Get Star. Adr. for XB 
and Bits Caller : 
Allowed to Specify 




ERR-OPNXT6J 



OFNSRC 



Search OFN Portion of 
SPTH Table for Matching 
Str. No. & XB Adii. 




When 
Rescheduled 



Set up Sched Test 
OFN,. OFNtKT - AC1 
MOISMS 



Unlock OFN 



(Error Ret ) 



( Return ) 



Success Ret with 
OFN in AC1 




Add new OFN to 
SPT Tble & Friends 



(ERR-OPNXIcT) 



Mark As Nnw 
For SPT Entry 



Access & Stor Adr ~ SPTH(OFN) 
Stor Adr - SPTIOFNi 

Str. No. -SPTO(OFN) 



PGTCAL 



If This Directory on This Str. 
Already Has Open Files, Store 
Its ALOC1 & ALOC2 Index 
Into the SPT Entry. If Not 
Make New ALOC1 & AL0C2 
Tble Entries. 



ASOF6A: 



Increment OFN Use Cnt in RH 
of A LOCI 



Update Shr Cnt for 
OFN in SPTO(OFN) 



SETXB1 



Map Index Btk 
Through PS8 Slot 




Mark OFNWRB 
bit in SPTH so 
OOMP will 
migrate tf-ia pg 



Vw (ERR-OPNXtJP) 



RGLCXB 



Release (Unmapi 

Index Blk 



return) 



002 
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SEQUENTIAL l/O-OSK 
(String & Byte Oev Oep Code) 




Get Bytt No. of 
Cur. Byte From 
FILBYNinJFNBLK 




No 



No 



Set EOF Flag 
in Status Word 



7=3=: 

^ Return J 



Yes 



SETWNO 



Sat Window 

PgUp 

Calls ASGPAG . 

To Assign a 

JSB Page 

Cltars FfLCNT 




Gat naxt byta 

From Window as Pointed 

toby FILBVT 



Increm. Bvta Count 
(FtLBYNI 



( Return ) 



Sat FILCNT to 
No. of bytes Left 
in Pila 




SETWNO 



Assign Pg 
from JSB 
Soaca 



Yes 




NEWWNO pS02 



Gat Naxt 

Pginto 

Window 



Deposit User byta 
in Buffer and 
Increment FILBYN 




Sat EOF Flag 

Update FILLEN to 
New Length 



UPOLEN 



Update OFN Length 
In OFNLEN Tbl 



SD1 
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Disk Oep Cod* to 
Update Window Pg 
(Movh to Ntxt Pag* 
of File! 

newvvnd) 



Routine to Convert Your JFN. PN to 
OFN, PN. Create* Long File Pg Tahle 
if Ligal and Requested 



Set Flag to Say 
Allow Pg Tble 
Create* 



f JFNOF5 ) 



OMOCHK 



ChkThat 
Structure 
Still Mounted 



If FILBYN > F1I.L6N 
Set FILBYN to FILLEN 





{ Error Return J 



SETMPG 



Unmap Old 
Page in Window 



JFNOF2: 



NEWI.FP 



JFNOF5 



Get OFN„ PN 
For This Pg 



SetUp 
OFN„ PN 



Chamge Pg 
Table for 
Long File 

zn 



If Error. 
Err- Return 






- FILCNT 



Return 




Store Pg No. in 
LHof FILWNO 



Create Pg 
of Zeros 



Map the Pg 
into Window 



Store Pg Adr in 
FILBYTSi Bytes 
Per Pg into FILCNT 




AOJCNT 



Err Return) 



Adjust FILCNT if 
FILBYN Not at 

Beqinning of Pg 



( Return Ji 



S02 



CLOSF - DSK 
Oev. Dep. Code 



DSKCL2 



^r Window >v Y» 


I 


Unmap Window Pg 
Return Space to JS8 
Free Space 


v. Pg in J* - " 


JNo 


I 


% — ^»^^™ 




GETLEN 




Update FILLEN 
Before Close 




♦ 




If Opened for Write and 
Have a Window, Update 
FOB Entries. FBBSZ. 
FBMOO. FBStZ 





(cntlng) 



Get OFN of 
PG Table 



RELOFN pCD2 



Release OFN 



CNTLNG 





Update FOB 
Last Oir Change Time 
(If Open for Write) 
Quota Info 
Pg Count for File 
Byte Size, Mode, Size 
in Bytes 



Count all 

Pgs in Use 
for File 



SETMPG 



Unmap Super 
index block 



RE LP AG 



Return Page 
to JSB Free 
Space 



RELOFN pCD2 



Release OFN 
of Super- 
Index Blk 




DSKDV 



Delete 
Excess File 
Versions 



UPODIR 



Update 
Directory 



Decrement OPEN 
File Cnt for Str. 

per 

(Return! 



CD1 
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CLOSF-OSK (Continued) 
Release OFN 



UPDO FN pCDS 



Write XB 

to 

DISK 



DASOFN pCD4 



Oeassign OFN 



(relofn ) 




Delete Pgs 
( DELPT ) 



Mark Delete 
Pgs Flag 



GETSHR 



Get OFN Shr Cnt 
from SPTO Tble 



Not Last Close 
of OFN 
RELOF6: 



OKSKED 



l Return J 



SETX81 



Map XB into 
PSB Map 



Touch Index Pg 
(So Will Be Brought 
Into Core if Not 
Already in Core) 



Decrement OFN 
Shr Cnt in SPTO 




If This is the 
Frozen Writer of 
the File, Turn Off 

The Write Bit 



( Return) 



SKPNWR pPF9 a 



If Writes in Progress 
for XB. RDISMS 
with Sked Test, 
Pg =„ DWRTST 



Lock XB in CST1 
So Won't Get Written 







PCD3 



CD2 



£ 



SCNOFN 



Move All of 
Pgt to Disk 



OFNOLN: 



R6LOF7: 



Scan XB & Release 
Alt Pes from Disk 
Bit Tbl for Str and 
Zaro Each Pg's Slot 
inXB 



DWNSHH 



Dacrant. OFN 
ShrCnt inSPTO 
(BUGHLT if Cnt 
Already 0) 



CLOSFDSK (Continued) 



( SCNOFN ) 



Setup to Cheek 
All Ptrs in XB 




SCIMOF3: 



Gat Ptr 



Scan XB & Release 
Only Good Pgi from 
Disk Sit Tbl 
Clear XB Slot Whether 
Pg it Good or Bad 





SCNOF4: 



SKPNWR oPF9a 



Wait for Write 
to Complete 



DEOSK 



Delete Disk Adr 
of XB from Bit 
Table for Str 




OFRQ 



Put Pg on Top 
of RP1.0 



RELCXB 



Release Temp 
Mapping 



Return j 



RPCST 



Fore* Disk Adr 
Back to XB 



CD3 
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CLOSF • DISK (Continued) 



Mov« File Page 
to it* Horn* on 
Disk 




SWPOTO pPFU 



Swap Pg* to 
Disk. Hanwwe 
PgfromCST3 
Entry 



Q Htturn J 



' Yn 


f Return \ 

\ 


'No 


Page Unauigned 
Fluih It 



SWPINW pPFIQ 



Swap Pg into Cora 
& Wait for Completion 



Oaiata from 
OST Tble 



OASORM 



Deassign 
Drum Adr 



I 

Q Returnj 



Deassign 
OFN 

foASOFN ) 



0*SPTH(OFNI 
0*ALOCX Field 
in SPTIOFNI 




No Mora Files Open 
for Oir, So Clear 
ALOC1 & ALOC2 
Entries 



0-OFNSHC 
Oecnmient Opim 
FilaCnt 



Unlock Pg in CJIT1 



Return 



CD4 
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CLOSFDISK (continued) 




UPD8TB 



Update Bit 
Table 



UPDOFO 



Write Index 
BIk to Disk 




SETMPG 



Map Index BIk 
Through PSB 



Set up to do 
chksum for XB 



Unlock OFN 



3 



r Return J 



Put Disk Adrs of 
Existing Pgs in XB 
Slots & Store 
Checksum in XB 



UDSKIO pPHY1 



Write XB to Disk 



MSETMP 



Unmap Index Block 

T 

f Return j ' 



CDS 
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CPENF-DISK Comments 



(1) OFN bits; 0=read, 10=write, ll=thawed, (Derestricted 

(2) For a long file, the OFN of index block is 
remembered in the JFN blk and used as the identity 
of the file by the ENQ/DEQ facility. 
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CLOSF-DISK Comments 



(1) All storage addresses placed in an index blk have the 
pointer type field set to immediate. 
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JSYS's CALLS 
MTA DEPENDENT LEVEL 

MTAOPN - Magtape Opening of a File OM1 

MTASQI - Magtape Sequential Input SMI 

MTAIRQ - Queue Up Specified IORB SM2 

MTASQO - Magtape Sequential Output SM3 

MTACLZ - Magtape Closing o.f a File CM1 
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OPENF- MAGTAPE 
DEVICE DEPENDENT CODE 




Called via Contents of 
OPEND (MTADTB) 



Lock Unit 



Mark Unit Open in 
MTASTS (Unit =) 



Error ") 



Error ) 



Error ) 



Unit ^______« N ^ 

["Already Opened^ * ( Error ) 
■> Jr Yes > — ' 




Error 



J 



Error J 




2. 



Initialize Per Unit 
Storage and Figure 
Bytes Per Word 



Store Magtape Parameters 
Density - MTDN 
Parity - MTPAR 
0-FILCNT, FILLEN, 

FILBYT (2) 



Init Units lORBs 
Init MTBUF & MTCUP 
Store Prog. Name & Logged-in 
Dir. Number in UOB 



Unlock Unit 

in MTALCK 



( Return ) 



3 



0M1 
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SEQUENTIAL INPUT - MTA 
(STRING & BYTE DEV. DEP. COOE) 
Called At JSYS Level 
Through 8INO (MTAOTB) 



MTAASB 



CUM ASGPAG to AfSiffi 
JS8 Pgs for 2 Buffers. 
Etch of Size Ree. Length. 
Store Adr of Buf Pgs in 
List Pointed to by MTBUF 




UPOSTS 



Update Status for 
This Unit (If Last 
Function Not a Raad)( 




CHKERI 



Chk IORB for 
Errors. (Rat if so) 



Tramlata No. of 
Hardwara Bytes 
to Usar Bvtas 



MTSIQO 




CLRINP 



ZaroFILLEN. 
FILBYN. FILCNT 

Mark IORB 
As Fraa 

Stan Buffer No. in 
MTCUB for this Unit 




0- 


FILCNT 


0- 


FILBYN 


No. of Bytes in 


8uf 


-FILLEN 



MTSQI1 



Step to Next 
Pg of Suffer 




MTSQIS 



MTIRQI pSM2 



Queue up any Free 
lORB's (Ready for 
Filling) 



Step to Next Pg of Buffer 
Byte Ptr for this Pg - FILBYT 
MIN (No. of Bytes Left in Buf. 
No. of User Bytes/Pg) - FILCNT 




Increment Buf Pg if Reading Forward 
Decrement Buf Pg if Reading Backward 



Return J 



MTSQI2: 



GETUBF 



Get next IORB for User 
to Empty. If Need to Blk, 
Setup Sched Test: 
IORB Waiting for..MTARWT 



Decrement FILCNT 
Increment FILBYN 
Get Byte from Buffer 



T 



( R « urn ) 



Next^X 
IORB 


s^ No 




Reedy?/ 
JY»s 




Q Return ) 
Unsuccessful Return 



SMI 
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Queue up any Free 
IORB*! for Filling 



C MT1RQI ) 




("mtairq ) 



Queue up Specified IORB 



Frames Cm-* IRBCNT 

Char Cnt - IRBOC 

FuncCode-IRBSTS 

(Adr of Lin 

of Buf Pgsr* IRBPB 



MTIRQ2: 



For Each Pg in Buf: 

1. Put Phy Pg Adr in UH 
of Each Buf Pg Ptr 

2. Call PHYSIO & De». 
Dtp Coda to Sat up Chan 
Command Word in Xfar 
List for tha Pg. 



Store at End 
of Xfar U*t 



Store Ust 

Tail.. Head - IRBXFL 



Data Mode, Density. 
Parity -* I RBMOD 
MTCHKA.. MTAINT 
•* IR3IVA 



QUEIR8 



Queue up 
IORB 



Q QUEIR8 ) 



Set Status Bits 
for IORB 

Step IORB far 
this Unit 

Set Adr of CDS & UOB 
for this Unit 



PHYSIO pPHYZ 



•Call Physio to 
Queue Request 



GEIED 



SM2 



( Return ) 
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SEQUENTIAL OUTPUT - MTA 
STRING & BYTE OEV. DEP. COOE 



Called at JSYS level 
Through BOUD (MTAOTB) 



MTASQO 




MTAAS8 



Aijign Buffer, 
Space if NMdcd 




Yei 



MTSOOO 



Output Buff 



3 



Step to Next Pg o/ Buf 

Byte Ptr for this Pg - FILBYT 

Zero Buff er Pg 



GSTIRB 



Get Next IORB 
forUsertoF.il 



MININo. of Bytes/Pg, No. of 
Bytes left in Buf) - FILCNT 



MTSQ03: 



MTSQ02; 




Decrement FILCNT 
Incramtnt FILBYN 
Store Byte in Buffer 



No 



( Return ) 

Successful 



CE^ED 



Unsuccessful 



Yes 



~1 
I Err-Ret ) 



Bvtes/Buf-FILLEN 
- FIUCNT 
- FILBYN 

(mtsqoi) 



Output Buffer 
C MTSQOO ) 

_3_ 



GETCS8 



Get IORB Adr. 



I 



Get Record Size & 
Convert to Hdw Bytes 




( Return } 



SM3 
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CLOSF - MAGTAPE 




CM! 



Unsuccessful 
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OPENF-MAGTAPE Comments 



(1) 



One can open for read and write only in dump mode, 



(2) FILCNT/Count of bytes left to use in current page of 
buffer. 
FILLEN/Count of bytes in buffer. 
FILBYN/Buffer byte number user is referencing. 
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CLOSF - MAGTAPE Comments 

(1) Since the monitor reads ahead, backspacing to just after last user 
record read may be necessary. 
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REQUESTING DISK/MTA I/O & INTERRUPT HANDLING FLOWCHARTS 

(PHYSIO LEVEL) 

DRMIO/DSKIO/UDSKIO - Requesting Drum or Disk Read/Write PHY1 

PHYSIO - Queue Up IORB Request for Disk, Drum PHY2 
or Magtape 

SIOl - Post IORB PHY2 

STRIPS - Start Unit Positioning PHY3 

STRTIO - Start Unit Transferring PHY3a 

PHYINT - Disk and Magtape Interrupt Handler PHY4 

DONIRB - Post IORB as Done ' PHY5 

SWPDON/UDIINT - Housekeep for PHY8 

Drum/Disk Done 

MTAINT - Housekeep for Magtape PHY9 

Done 

SCHSEK - Schedule "Best" Seek Request PHY6 

SCHXFR - Schedule "Best" Transfer Request PHY7 
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REQUESTING DRUM OR DISK READ/WRITE 
(PHYSIO LEVEL) 



Called From UPOOFN for 
UDSKIO I Writing Out Index Blk. 



OSKIO 
DRMIO 




PAG EM Interface 
DRM/DSK I/O 



If Writing, Set 
DWRBIT Bit in 
CST3 Entry for Pg. 



Set IS.SHT Bit and Function 
Code into Short IOR8 (1 Word 
Blk in CST5 Entry for Pg) 



Get I0R8 Adr for 
Pg (ia CST5 + Pg No.) 



PHYSIO pPHY2 



Enqueue 
I/O Request 



{ Return J 



GETIRB 



Get IORB + CCW Block 
From Pool. Wait if Nee. 



Store Oisk Adr. Count, 
Function 81 Specific 
Status Bits in IORB 



Store UOISIE in IR8IVA 
if Caller Wants Error on 
Offline Unit. 



Get CDB & Unit- 




Yes 



Get Unit Type & Construct 
CCW List & Store in IORB 



Set Up Err 
Code of a — 1 




UIOXIT 



Store 

Tail., Head of CCW List 
Int. Routine Adr, UOIINT 
in IORB 



NOSKED 



PHYSIO pPHY2 



Enqueue I/O 
Request 



OKSKEO 



-*■"■ UI03: 



(IORB ADR,, 
UOWDONI - AC1 
POISMS 



Wait for Done on this 
IOR8 as a Pg Fault 




PHY1 
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Call to Qimu* Up IORB 
PHYSIO I for Oiik/Drum or MTA 



[pHYSIoI 



Pott IORB 



SMUpLoal 
StkPtr 




Rnwr* Caller's 
StkPtr 



"ZET 

( Rtturn ) 




GSTCUB 



0*tCDB& 
(JOB Prom 
PACEM Adr 



6tt Cor* Pa No. 
From Offset in 
CSTB 



5 ton Unit No. Into 
CST3 Hntry for Pa, 



■» SIOR2: f 



On Units Dhp Tbl« 



Tum OH PHYSIO 
PI Chwinah 



Oct Unit's Stilus 
Word IUOBSTS) 




UDSPRO(UOBOSP) 



Sm if Request 
Should Go Through 
Position Cvdt 




Decrement Fairness 
Count for the Unit 
in UOBPCT 




PHY2 
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Hert When R«quait 
Needs No Positioning 



Add Req to PWQ 
SI03 




STRTPS pPHY3 



Unit Free 
Start Positioning 



Enable PI 



( Return ij 




PHY2i 
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Hera to Start Positioning 
for an IORB 



c 



STRTPS 



D 




BUGCHK 

Inconsistency 

Chk 



If Than it a Controller, 
Sat KS.ACT in KOB 
(BUGHLT if Already Set) 



Sat US.ACT & US.POS 
Bits in Unit's Status Word 



SETIO 



Clear All Err Bits in ' 
IORB Status Word 
Store Overdue Time 
for Xfer in UD8 
Get Channel's Oisp Adr 
from CD80SP (COBI 



CDSPOS (Chan Oisp Adr) 



Dispatch to Lower Level 
Positioning Function 




CLRPOS 



Clear Positioning 
Active Bits. 
US.ACT & US.POS 



C 



RETURN 



Unsuccessful 
Return 



PHV3 



96 



Here To Start I/O 
on an IORB 



Q STRTIO ) 



Get STRTIO Exit 
Adr from IORB 
(LH of IR8IVA) 

OSK-UDISIE 
MTA-MTCHKA 




Execute Routine 
DSK-Sets Bin if 

Unit Offline 
MTA-Seu Bit if 

ABORTF on 



Set Chan, Control. & 
Unit Active Bits in 
COB. KDB, & U08 

Mark in COB that a Unit 
i( Holding the Chan 



X 



SETIO 



Set Up For IO— Clear 
All Err Bits & Set 
Overdue Time 
(Now +17 See) 



COSSIO (Chan Di«P Adr) 



Go Start I/O at 
Lower Level 




RETSKP 



No. Offline 



Successful 
Return 



3 



CLRACT 



Clear Chan & 
Unit Active Sits 




Clear US.OIR & 
US.OMS Bits (Don't 
Need any Longer 
for Oper. Intervention) 



OFFTWQ 



Remove Req 
from TWO 



OONIRB p PHYS 



Flag as Done 



(_ \ Unsuccessful 

R,turn ) Return 



Yes 



Set Operator 
Intervention bit 
Clear Overdue Timer 



Return 



Unsuccessful 
Return 

PHY3a 
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I PHYINi I 



INTOON: 



Sana ACi in PHYACS 



Kara Whin Int. Oi>. 

Hm e**n Otttrminad 

ICOB Adr Indi- 
cant thii) 



OFPTWQ 



& 



Ramova IORB from PWQ/TWQ 



Sttup InttrruRt POL 
(SwrnatPHYlPO) 

Gat Channel'! Oiip. Tbl 
Adr. ia COBOSP ICOBI 



CLRACT 



Noia No Longar Activa 



COSINT (Ghan Diio Tbl Adr) 



Aiwlyia Causa ot Intarrupt 
at Channtl Oap. Laval (1 1 



OONIRB pPHVS 



Poit IORB h Dona 



Error 




Shut Down Stk Command 


> j» 


' Yai 


(0 -CS.AC2) 


[No 


'' 




SCHSEK pPHV8 



Schadula S«k» 
(If Naadad) 



SCHXFR pPHY7 



Schadula 
Traiufart 




( CDBJENlCOBl ) 



Raitora ACj and 
Oismm Int. 



Honor Raquan 



Hara Whan 
lORBTarminatn 



OONIRB pPHYS 



Pott IORB » Oona 



OPFPWQ 



Pull Prom PWQ 



CLRPOS 



Claar Positioning Flag 



Or 2nd Command 
Activa Bii (CS.AC2) 



QPFTWO 



Pull From TWO, 



PHY4 



OONIRB pPHYS 



Poh IORB « Oona 



SCHSEK pl»HY6 



Schadula Staki 




SCHXFR pPHY7 



Schadula Trainsfarj 



J 



INTERR 



Error 

Blk Setup for 

Unit? 



Yes 



^ Unit \, 
Transferring 


w Yes 


Set Err Rec. 
Sit for Chan. 









No 



ERRSET 



Create Error Blk 



UDSERR (Unit Oisp Adr) 



invoke Error Retry 




No Done with 
Recovery 



Gear Err Rec 
Bit if Xferring 




iNTOON 



PHY4a 
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Hare to Port an IOR8 Compieta 



( OONIRB ) 



Sat Done Flag 
in IRBSTS 




Sat Error Bit 
IS.ERR in IORB 



EHRFIN 



Tarminata Err 
Recovery if Needed 




DONIR1: 



(Set Int Disp. Adr. 
From Long IOR8 Entry 
(RH of IRBIVA) 



Yas 




Y« 



Set Error Bit, SWPERR, in 
Short IORB for PAGEM 



SWPDON pPHYS 



Notify 
PAGEM 



,JLT 

( R « ) 




(bughlt) 



UDINT pPHYS or 
MTAINTpPHY9or 
MTDINT (Dump Mode) 



Do Dev (Disk/MTA) 
Dependent IORB Oone 
Code. (The Two MTA 
Interrupt Routines 
Perform the Same 
Cleanup Tasks) 



CED 



PHY5 
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(_ SCHSEK ") Schedule Seek 
1 




-X^ Oeer.^V 

<^Hd Pref Cnt^ 

>iv Expired v"* 


Yes 


Reset Rd Pref 
Cnt(fOIS) 




JNo 










Mirk Reads 
Get Preference 


1 










1 


SgK1: 


1 








Oat Cylinder 
of Request 






SEK3: 




Y« 



Movie Req from PWQ to 
TWO & Advance Ptr. 



SEK2: 



E 




Get Best Req & Remove 
it from its Position in the 
PWQ to the Beginning 
of the PWQ 




( Return J 



Sean Algorithm 

Remembers 

'Best' 



SEKS: ' 



Get Next 

IOR8 

Request 



Sean Algorithm with 

Read Pref Remembers 

'Best' (21 



Advanee Ptr 




PHY6 
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P0S1 



Gat Head of PWQ 







ONTWQ 




Append to 
TWO 




*No 




t 


'Request's. 


OFFPWQ 


Require 
Positioning^* 


Pull Request 
from PWQ 




Return 



PHY6a 
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(^ schxfb"*) schedule transfer 



Rtrat rurnwi Cm 
(f D40I in CDBFCT 



Six A« 
Currtnt B«t 




STRTIO pPHY3* 



Arttmpt to Start 
I/O 



Now Ictlt 



UDSLTM (Unit Diip Toll 



CjII Okt. Dob Cod* to 
Q*t Best Lanncv Rtq 
From All Xf«r 
Rtqutsn for tha Unit 



If Nomkp ft • turn. 
BUGW.T (UntxpMtMl 
IATOPT Failure) 








Enter Command 
Stk SelieduUr 



9HY7 
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XFRO 




Samp to Continue Scan 
From Last Active Unit 
(Kept in COBCUN) 




XFR4: 




XFRCHB: 



If Unit Available, 
Move Special lORB 
to Head of TWO 



XFRX 



Try to Start I/O for 

this Unit 

Call STRTIO pPHY3a 



XFR7: J 




XFRS^N. 


Get Next Unit 


XFRSc/Nw 


v^UnitN. 

•^Present, Avail 8T^ 


No 


./Back to^v 
"^ Starting Unit >"■"" 

V ? yT NO 


I Yes 




T Yes 



XFRX 



Try to Start I/O 

for this Unit 

Call STRTIO pPHY3a 




XFRX 



Try to Start I/O 

for this Unit 

Call STRIO pPHY3a 



Pull IOR8 from TWO 
Indicate Hard Err- 
Post as Done (OONIRB 
PPHY5) 




XFR2 

Continue 
Chan Scan 



No, Try Another Unit 



Return 



No 



PHY7a 
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Command 

Stack 

Scheduler 



UDSLTM(UnitDispTbl) 



Compute Best Latency 





-*»-i 



Save '8est' I ORB 



ONSTWQ 



Move It to 2nd Place on TWQ 



STKIO 



Stack Command 

Call CDSSTK (Chan Dlsp Tbltl 



Return 



PHY7b 



105 



•INTERRUPT DONE" DSK/DRUM DEPENDENT CODE 



C SWPOON ) 



Called When Short IORB 
Done for Disk or Drum 




Incrern. PSKED 
ITell Schad Rd 
Complete) 



SWPOI 



Clear Write Bit in 
CST3 Age Field 



Store Rd Don* for 
Pg Stat* Coda in 
CSTO Entry 



I^Raturn) 



Pg Suta ■ ^s, 
•ite in Progress*. 


No] 


Oecrem. IOIP 


^V^Yea 







Forte Waiting 

for Writa Completion 

IDWRCFU#< 

? 

"No 



Yb 



Incrern. PSKEO 



Was 

''Page Deleted?"* 
JCST2 Entry-01, 

No 



I* IOIP-0 (Writes 
All Completed) , 
Clear OWRCFL 



Put Pg on Deleted 
Queue & Set Pg 
State to Deleted 



If Error on Writa, Clear Error Flag 
Mark Pg Still Needs Writing 




Yes 



• 


(^Return ) 




; 


i 




ONRQ 


No 


Put Pg on End 
of RPLQ 



OFRQ 



Put Pg on Top 
of RPLQ 



ONRQ 



Put Pg on 
End of RPLQ 



Return J 



f UDIINT J Called When Long IOFIB Oone 
^ 1 ' for Oi*k I Infrequent Case) 



Increment Page I/O 
Satisfied Flag - 
(PSKEDI 



f Return \ 



SWP6R1 J Swap Error 



PHY8 
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SUGCHK 
Swp Err in 
Index Blk 



SWPERX ) 




FNOFFG 



Find Type of 
Fork Page 



Oiipatch to 

Correct 

BUGHLT 



T 

(bughlt) 



"INTERRUPT DONE" MAGTAPE DEPENDENT CODE 



Called When Non-Dump Xfer Done For 
MTA At Interrupt Level 



Imtaint) 




MTAINE: 



Yes 



Check All 
Error Flag* 



MTAIND 



Unlock Pgs & 
Mark Done 



MTAKIL 



— -^BUGHLT*) 



Int. Received for 
Nonactive I ORB 



MTAIND 



Unlock Pgs & 
Mark Done 



( Return ) 




Only Want To Abort 
for a Good Reason 



Kill All lORB's Left 
On Queue for This Unit 



C Return ) 



( MTAKIL ) 



Set "Abort Ail lORB's 
For This Unit" 
Flag (ABORTF) 



PHYKILL 



Dequeue All Nonactive 
lORB's From TWQ 
for Unit 



Mark All lORB's 
as Aborted 
(IRBAB Flag) 



Call MTAINT 
for Each IORB 
for This Unit 



( Return ) 



f MTAIND) 



Mark Buffer Ready 
Flag (IRBFRI & 
Clear Active Bit 
IIRBFAI 



MULKCR 



Unblock All 
Buffer Pgs. 



Decrement No. of 
Requests Pending 



MTAINT is 
Being Called 
Recursively 



PHY9 



C Return ) 
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Requesting DISK/MTA I/O Comments 
ilOl 

(1) The algorithm for queuing up a MTA request is: 

If the request requires positioning, append the 
request to the PWQ. 

If the request requires no positioning (i.e., 
Read/Write Forward or Read Reverse) append the 
request to the TWQ only if the PWQ is empty. 
Otherwise, append it to the PWQ. 
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DSK/MTA Interrupt Handling Comments 



PHY I NT 



(1) The channel dependent routine (RH2INT for RH20S) is 
called to analyze the interrupt. Lower level routines 
called by RH2INT (i.e., Unit dependent routines) return 
an argument in AC, P4, to PHYINT to indicate whether to 
dismiss the interrupt (P4 » 0) , to schedule another 
channel cycle right away (P4 < 0) or to housekeep the 
current request (P4 > 0) before scheduling another 
channel cycle. The channel dependent routine also 
records error information so that PHYINT can see if 
error recovery is in progress or should be started. 

The request to dismiss (P4 = 0) is invoked for example 
when the done flag is on and the channel is not 
occupied. The request for an immediate channel cycle 
(?4 < 0) is made when a positioning done interrupt has 
occurred and there is no transfer in progress. Transfer 
Done requests will require further housekeeping (P4 > 0) 
by PHYINT before scheduling another channel cycle. 



SCHSEK 

(2) The scan algorithm with read preference in effect 
performs as follows: 

Take the next higher-numbered cylinder read request from 
the current cylinder. If none, take the next 
higher-numbered cylinder (write) request from the 
current cylinder. 

If none, take the lowest numbered cylinder read, request 
from the current cylinder. If none, take the lowest 
numbered cylinder (write) request from the current 
cyl inder . 
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JSYS CALL FLOWCHARTS 
TTY DEPENDENT LEVEL 

TTYOPN - Teletype Opening of a File OTT1 

TTYIN - Teletype Sequential Input STT1 

TCI/TCIB - Get Character from Line's 

Input Buffer STT2 

TCIO - Get a Character STT3 

TCOE - Echo Character STT5 

TTYOUT - Teletype Sequential Output STT4 

TCO/TCOB - 1st Level: Output a Single 

Character - Translate According 

to Fork's Specification STT5 

TCOY - 2nd Level: Do Links & Formats 

for a Particular Device STT6 

TCOUT - 3rd Level: Do Buffering 

and Output 1 Character " STT7. 

TTSND - Send Character to Line STT8 

TTYCLS - Teletype Closing of a File CLTT1 
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Setup in AC1 

UneNo.„TSACT1/2 
and MDISMS 




OPENF-TTY 
Dev. Oep. Code 



CHKAPD 



SetWRTFBitif 
Append Requested 



TTYOP1 




RETSKP) 
Successful 
Return 



LCKDVL 

Lock the DEV Tbls. Lock, 

DEVLCK; & Go NOINT 



FNDUNT 



Get DEV Tbls. Index 
for this Unit 




Store this User's Job No. 
for Line in DEVUNT Tbl„ 



Set Open Bit, DV%OPN. 
for Una in DEVCHR Tbl. 



OEVAV 



See if Device is 
Avail, to this Job 




Unloek DEV Tbls. 
Lock. DEVLCK 



TTOP3: 



OKINT 



C ErrRet-OPNX7 ) 



TTYASO 



Assign TTY 
if Possible 



Setup to Return 
with SIZF Bit Set 




Yes 



© 



7T7 

C RETSKP) 

Successful 
Return 



TTYOP2: 



Unlock DEV Tbls. Lock 
& Go OKINT 




( Return J Unsuccessful 
v — — — — ' Return 



OTT1 




G«t 1 Input Char SEQUENTIAL INPUT - TTY 

for the lim STRING & BYTE OEV. DEP. CODE 



MC, JFN, Hold-1 L/^T 



Get Una No. for 
Job from JOBPT 



,|Ytl 



If 1st 3 Char of 0«v. Namt 
ara TTY, Gat Control. TTY 
No. from JOBPT 




Yes 



Gat Char from 
RSCAN Buffer 



Call Input 
Routine 
in TTYSRV 




Ye* 



Perform RESCAN 
Housekeeping 



Use Normal Mode 
for TTYs 



Gat Dispatch Adr., 

TCI 
(Routine that Allows 
Translation} 





Dispatch to 

TC1/TCIB O.STT2 
to Input Char. 



TTYATW 



Wait for Attach 




ULKTTY 



Unlock Dyn. Data 
for Line 

(Allow Alloc.) 



LCKTTY 



Lock Dyn. Data for 
Line (Prevents Deailoc.) 




ULKTTY 



Unlock Dynamic 
Data for Line 



Indicate Error to 
Cailer (Set ERRF Sit) 



No, (i.e. 
400000,, Una) 




Setup to Return in 
AC, A, Just Byte Size 
of Char Specified 
at OPENF 



C Return ) 



C Return J 
(Char in AC, A) 



^^^^^ Get Char From 
C TCI ) Input Buffer 

— ~"~"^ Called from TTYIN 



Get Binary Cher 
C TCIB ) from Input Buffer 
Called from TTYIN 





Indicate Already 
Echoed 


Yes 
Ye» 


^>^*^Repeat^<w 
Last Char? 




" S S S <BKJFN?>^' 






JNo 




Return LF with 
No Echo 


^^ Last Char ^> 

s. WasaCR <, 

\. ? ^/^ 






jTno 




TCIO pSTT3 


Get Next Char 
from Buffer 




Cleer Repeat Char Flag 
Get Last Char Input 



Set Flag to Indicate 
Binary Terminal Mode 




!'" 






TCIO pSTT3 






Get a Char 





TCI3 




TCITT1 



Chk for TTY Int. 
& Let PSI Handle It 



TCI2: 



Yes 



TCITTI 



Test for TTY Interrupt 
on this Char & Let 
PSI Handle It 



Was 
It a TTY 
Interrupt 

•No 



- ( Return 

Unsuccessful 
Return 




TC1B1: 



Setup to Return in 
T1 Char. * Parity 




Yet 



TCIR 



f Tc ' lECO" ) Do 0,fer,ed 
V TC '. ECO ) Echo if Nee. 



\y*r char ^N^ 


Echo CR-LF 
Call TCIECO 
for Each Char 




jTno 










TTRAIS 








'Raise' Input 
Char if Nee. 






1 


1 








TCI ECO 








Echo Char 
if Necessary 


1 




-1- 








Input Request Means 
Implicit Clear of 
CTRL/O so Clear 
CTRL/O Flag. TOFLG 



TCOE pSTTS 



Echo Character 



Save Last Char in TYLCH 
in Oyn. Data Block for Line 



Will Echo Char if 
Not Echoed by Sched. 



( Return J 



v ' Successful Return 



STT2 




Get Char Prom 
J Line Input Buffer 
Called from TCI/TCIB 



TCI01: 



OKSKEO 



Make Sura No Other 
Fork is Waiting, 
Then Go Into Input 
Wait 



TTICIMO 



BUGHLT if No 
Ptr. for Char. 



TC111: 

1i There"*' 

"is Fork Waiting'* 

for this Line> 

? 

No 



TCIF1: 



Yes 



TCIF2 



Step to Next Buffer 
if at End of Current 8uf. 



Get Next Char. & 
Store Updated Ptr. 
in TTIOUT 



Save Data Mode 
Record this Fork is 

Waiting for TTY 

(in TWFRK) 
Indicate No Forced 

Wakeup in TTFWK 



Reduce Cnt of Chars 
in Buffer 




Dispatch to 
Function Table 

TTXXVT 
at Offset, 
TTVT32 
(FE Disp. Adr. - Ret.) 
(PT Disp. Adr. - TC1PTY 
(Input Char.)) 



Perform 

Housekeeping 

Tasks 



( RETSKP) 

Successful 
Return 



ULKTTY 



Unlock Dynamic 
Data Blk for Line 



Get into AC1 

Line No.,. TCITST 
& MDISMS 




ULKTTY 



Release TTY Lock 
& Go OKINT 



TTFRKT 



Resolve Conflict by 
Halting Fork if it's 
Inferior or Putting 
it in Fork Wait 
if Not 



C Returi i"*) 
Non-skip Return 
to Raverify TTY 
in Case We Blocked 



^-^^ Non-Skip Ret to Say 
> * a Block has Occured 



STT3 
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Yes 




Output 1 Char 
to the TTY 



SEQUENTIAL OUTPUT - TTY 
STRING & BYTE DEV. DEP. CODE 




If 1st 3 Char of Dew. Name 
are TTY, Gat Controlling 
TTY No. from JOBPT 



Setup to Send Out in 
AC, A, Just Byte Size of 
Char Specified at OPENF 



Dispatch to 

tco/tcob psrre 

to Output Char 




" 






ULKTTY 






Unlock Dynamic 
Data for Line 










( Return ) 



Call Output 
Routine in 
TTYSRV 



Yes 





Allow 
Translation 



TTYOUB 



Get Dispatch Adr., 
TCOB 



Get Dispatch Adr., 
TCO 




TTYATW 



Wait for 
Attach 



LCKTTY 



Lock Dynamic 
Data for Line 




ULKTTY 



Unlock Dynamic 
Data for Line 



Indicate Error to 
Caller {Set ERRF Bit) 



C Return ) 



STT4 



1 1 7 



TCO - 1« t_avei • Translate According to Program's Desires 
TCOY - 2nd Laval - Do Links & Format for a Particular Oavica 
TCOUT • 3rd Laval ■ Do Buffering, ate. 




\ 1st Laval: Called From TTYOUT 
/ Output a Single Char. 



( TCQB ^ 1n Levsl: Ca "* d From TTY0UT 
v J Output a Binary Char. 



} Save Li 



Line No. 



Yes 



TCOB1: 



Get 7 Bits of Char. 
8t Parity 



Get Low Order 
7-Bits of Char. 




TCOU1 pSTT7 



Output the Char. 
Without Adding Parity 



C \ Echo Character 

TCOE J Called from Sched. 
IT 



If in Page Mode, Clear 
Line Position Within 
Page to Prevent XOFF 




Get Output Control Mode Bits 
for CTRL Char. 

00 - Send Nothing 

01 • Indicate, ie. t 

10 • Send Actual Code 

11 • Simulate Format Action 
(For Escape, Use S) 




TCOY pSTT6 



Call Level 2 to 
Output the Char. 



Get Char, into AC1 
(^ Return J 




Return 




TC1D: 



Convert Char, to 
Printing Equiv. 



Get t Code & if 
Echoing (IMECHF * 0), 
Incr. LINKF Flag 



I 



TCOY pSTT6 



Print Indicator (i.e.t) 

— T~ 



TCOY pSTTS 



Print Char. 



If Doing Echoing. 
Deer. LINKF Flag 



QciQ 



STTS 
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2nd Level: Called from TCO/TCOE 
C TCOY J Handle Dev. Idiosyncrasies 
• and Character Accounting 




TTOHA 



Account Spacing 
Performed by 
Half Duplex TTY 




"ittdi: 



Yes, Echo CTR L Fune. 



Use Char. Code to Index in CHITA8 
to Pick up Oisp. Adr.: 
TCOUT pSTT7 

or 
Format Routine (ie for CR, FF etc.) 
(Later Calls TCOUT) 



Output TChar. 
& Account Space 



( tcop ^ 



Step to Next 
Position on Line 



Call Routines to 

Output CR & LF 

& Reset Line Position 




TCOUT pSTT7 



^Return"*) 



STT6 



Output Char. 
(3rd Level Output) 



C Return ) 
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C TCOUT ^ 3rd Level:' Called From TCOY/TCOB. 
^ ■ ' Do Buffering & Output 1 Char. 



Do Parity Logic By 
Executing Instr. inTbl 

TTXVT 
at Offset 

TTVT12 ,_ 



Scan Link Word, 
Sending Chan, 
to Lines Specified 




r" errvrrn \ SD8C ' a ' Sched Entry Point When 
V .° | * Entering from TTEMES 



If Parity Bit Needed 

For Char., Do Parity Logic 

By Executing Instr. in Tbl. 

TTXXVT 
at Offset 

TTVT12 




TCOU6 



Go Store in 
Output Buffer 



Setup Sched. Test Word 
Line No.„TCOTST 
& MDISMS 



Yes 



Try to Assign 
Needed No. of Buffers 



Step to Next Buffer 

if at End of Current Buf . 




Store Byte Ptr. (to 
New Buf) into TTOUT 



Setup Sched. Test Word 

No. Needed,, TT8UFW 
& MDISMS 



Store Char, in Output Buf. 
Updated Ptr. in TTOIN 

& Updated Cnt in TTOCT 




TCOU5 



C sTRTOl ') StBrt ° UtpUt t0 
^ ■ * Line if Nee. 



Turn on DLS Chan. 
& OKSKD1 



Y« 



STRTOU 


Start Output to Line if Needed 


Dispatch to Table 


TTXVT 


at Offset 


TTVT13 


(Disp. Adr - STRTOI for TTFEVT) 



Return ) 



I Return"*) 




TTSNOO 



Send Char. Routine 

NOSKD1 

Turn Off DLS Chan. 

Call TTSND pSTT8 
Turn On DLS Chan. 



<T\ ** ^ *jr m. m 



Callable from 
Non-PI Context 



Sand Char, to Lin* 
( TTSND ") Called aT '"tirrupt Level, or 
^ ■ ' in Schad/Procesi Context with 

TTY Interrupts Oisabled 



Gat Next 
Char. 




<nfHsD?"! u ^' Xfaf 



via tha DTE20 



( Ratum ) 




OTECHO 



Output via 
Secondary 



Set Waiting for 11 Done 
& Line Active Flags 
Increase Cnt. of Bytes in 1 1 



( Return) 



Clear Output-Active Flag 



Setup Nee. Args 
for Call to OTESRV 



Get Buf Ptr from 
TTOOUT. (SUGHLT 
if No Ptr.) & Save it 



Step to Next Buf. if 
at End of Current Buf. 
& Update Ptr. in TTOOUT 



Call TTRLOB to Release 

Output Buffers 
If Int. On Empty Output 
Buf. Requested. Put 
a Word in BIG BUF 
with Bit TTOIRQ Set 
(Sched. (TTCH7) 
Will Find It) 



( Return J 



OTSNGL pOTEl 



Go Oo a Single Request 




( Return ) 



Get Next 9-Bit Char. & 
Reduce Cnt. in TTOCT 




Simulate CTRL/S 
(Set TTSFG Flag) 



Get Char & Parity 
(Low Order 8-8it>) 



BUGCHK 
TTSNO-Unrecognize 
Escape Code 




Deer. Bytes in-11 
Restore Orig. Ptr. in 

TTOOUT 
Incr. TTOCT 



INTRST: f G «>. SchedT Retry 



Note Not Waiting 
for Packet 

(ie Clear TTFPK! 



Get Line No.. Time Until 
Event (•<)), & Disp. Adr.. 
(-TTSN10! 



TTQAO 



Compute Time to Oo Function 
for Line & Save in TTIME 

Save Disp. Adr. in TROUT 

Incr. TTQCNT 

Set Scan Ptr. to Here if 
First Entry 



Call Dev. Dep. Code to 
Send it to TTY by 
Dispatching to 

TTXXVT 
at Offset 

TTVT23 
(FE Disp Adr- TTSND1) 
(PT Disp Adr - Ret) 



Return ) 



( Return ) 



STT8 



121 




CKJFTT 



See if JFN is 
for 



LCKOVL 



Lock the OEV Tbls. 
& Go NOINT 



FNDUNT 

Get OEV Tbls. Index 

for this Line 



OEVAV 



Sea if Davice is 
Available to this Job 




GTCJ08 



Gat Controlling Job 
for this TTY 



CLOSF-TTY 
Dev. Dep. Code 




RSTSKP) 

Succassful 
Raturn 



TTYCL4: " 



Unlock DEV Tbls. 
Lock, DEVLCK 



OKINT 




Is It 

This Job ^r- — , mj. Ln.nr ii i I . , 

-, ^S^ (ERR RET-0EVX2) 

No, Shouldn't 
Happen 




TTYDEA 



Deallocate Dynamic 
Data for this Line 



TTYCLO 




Indicate No Job Owns 
Una in DEVUNT Tot. 



Indicate Line No Longer 
Opened (DV%OPN Sit) 
in DEVCHR Tbl. 



Unlock DEV Tbls. 
Lock, DEVLCK 



OKINT 



CRETSKP) 
Succassful 
Return 



TTYCL;2: 



Unlock DEV Tbls. 
Lock. CIEVLCK 



OKINT 



If Suppose to Bik, Setup 

ACI/Linn No.,, TSACT3 
and Set 8LKF Bit 



("Return ) 

Unsuccessful 
Return 



SCHEDULER TTY INPUT ANALYSIS & STORAGE 



TTCH7 - Moves Characters from the Big Buffer. 

to Line 3uffers SCHTT1 

TTCHI - Initiates a PSI Interrupt if 
Needed, Echoes if Appropriate 
& Wakes Up Waiting Forks SCHTT2 
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SCHEDULER TTY INPUT ANALYSIS & STORAGE 



C 



Sched. Short Cycle Task 
xjch7~\ Moves Chan from Big Buf 

^^^M*^^y M t tin Rliffar* 




to Line Buffers 
Do Dev. Dep Functions for Lines 



Yes 



TTCH7X: 



Incr. Ptr. & if at 
End of Big Buf., Set 
Ptr. to Beginning 




Return ^ 



TTCQLN 



Setup to Check 8 
Lines for Special 
Requests 



Get Next Entry 



(Line No. + Char.) 
Deer. TTBIGC Cnt. 



Deer. Line's Cnt. in 
TTFBB of Big Buf 
Entries 



Do 
Next 
Char. 



SNDXON 



Send XON if Needed 



TTPSRQ 



Go Wake 
Up Process 





DOLINE 



Do Line's Req if it's 

Time to Do it. Where 
Oisp Adr is in TROUT 
in Line's Oyn. Data Blk 

Deer, TTQCNT if do Func. 

Housekeep Message Blk 
or Output Buf if Nee. 



Get Next Line 



Yes 



No, 
Shouldn't 

Happen 



TT7CX; 




Start at this Line Next 
Time {Store it in TTCQLN) 



Return ^ 



Get 7 Bits of Char, 
+ Parity 




TTCHI pSCHTT2 



Put Char, in Lines 
Input Buffer 



Set TTCON Flag & 
Dispatch to Tbl 

TTXXVT 
at Offset 

TTVT17 
(FE Disp Adr«TTCON1) 



(1) 




Clear TTCON Flag & 
Dispatch to Tbl 

TTXXVT 
at Offset 

TTVT17 
(FE Disp Adr. - NTYCOF). 



\2) 



C Return ^ 

« 



SCHTT1 



Callad fr 

TTCH7 

inittitas 

Echoes i 
Waiting 


am: 

f Char. Found in 8 

a PSI Interrupt if N 

f Appropriate & Wa 

Porks 


gBuf: 
eeded; 
kesup 




( TTCHI ) 






STAOYN 








Chk far Fully 
Active Line 






^ Active ^ 




/ttctn^ 


^N*. 1 ,S 


"'No 


lypSCHTTa 
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Line Not Fully Active 
and/or Has No Controlling Job 




Go Create Job 

on Line if LOGINs 

Allowed 



Return V^- 



TTCH73: 



Get Bell Clear 



TTEMS 



Send Short Message 
(i.e. Bell from 
Scried. (3) 



Send Beil 

& Lose 

Char. 



C Return) 



Have TTY 
Interrupt Char. 



Deferred 

Char. 

?. 



Yes 



Last 

Inp. Char. Same' 

as Current 

Char. 



No 





No„ Immediate 


* \v^ 


1 


r 






4 Yes 


TTCLPS 






TTCIBF 


Clear Pg Ctr. 


Clear inp. Buf. 
(on Double Int.) 


i 


, 





TTFWAK 



Force Wake 
(So Program Can 
See Interrupt 



TTPSRQ 



Request Int form 
PS! System 




Smash Char, on 
Top of Last Char. 



Incr. Cnt, of Ints. 
(TTINTSr 



C Return ) 



~T~ 

C Return"^ 



SCHTT3 
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Scheduler TTY Input Comments 
TTCH7 

(1) The carrier-on routine for the FE device is TTC0M1. 
If the line is in use or a job is being created, it 
just returns. Otherwise, it creates a job by the 
CTRL/C mechanism (i.e., putting a request in 
Scheduler's Request Queue, SCDRQB) before re- 
turning . 

(2) The carrier-off routine for the FE device is 
NTYCOF. It flushes outputs and issues an interrupt 
via the PSI system if process has enabled for 
carrier-off interrupt. It then issues a monitor- 
internal interrupt via routine, PSIR4, which causes 
the top fork to go to JOBCOF in MEXEC to cause the 
job to be detached. 



TTC7M 



(3) TTEMES is called at Scheduler Level to send a short 
message to a line. If the line is active, it 
appends characters to the line's output buffer. If 
the line is not active, it creates a message-length 
dynamic block for the line and puts the characters 
into this block. 

TTEMES calls SCDTCO (pSTT7) to output each char- 
acter via TCOUT to the buffer or message block. 
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REQUESTING DTE OUTPUT & OTE INTERRUPT HANDLING FLOWCHARTS 

(DTE PROTOCOL HANDLER) 

DTSNGL - Queue Up a Single Character Output Request DTE1 

DTEQ - DTE Request Queues for RSX20F Protocol DTE1 

DTESKD - Start a To -11 Operation DTS2 

SKVER1 - Process RSX20F Packet DTE2 

IMTDTE - DTE Interrupt Handler DTS3 

ONI IX - To -11 Done DTE4 

DEQDTE - Dequeue Completed Request, 
Post it, and Schedule Next 

One DTS4 

TTYINT - Complete a TTY Output 

Request DTE5 

DNSNGL - Post Single Character Done DTE4 

DINGME - 10 Received a Doorbell Interrupt DTES 

DOFRGM - Start a To -10 Transfer DTE7 

DN10RS - To -10 Done DTE3 

TAKLC2 - Process To -10 Done for 

RSX20F Protocol DTE9 

BIG.ST2 - Store Character into the 

Sig Buffer • DTS10 
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REQUESTING DTE OUTPUT 

Called From Interrupt, JSYS 

& Scheduler Levels 



Queue Up a Single 
tOTSIMGL') Char Output Request 

(Called from TTSND pSTT8l 




Add Line No. & Byte to 

Single Packet 
Link Packet to OTEQS Queue 

if Not Already There 
Update Packet's Byte Cnt 

& Flag Bits (If Full, 

Sat SNGAVL Bit) 
If DTE Inactive, Start It 

Call DTESKD pOTE2 



I 



( DTEQ 1 



CRETSKP^ 
Successful 
Return 



1 ■ Ci 

I 



DTE Request Queue 
for RSX20F Protocol 
(Called from DTSNGL, 
Sched. & Interrupt Levels) 



Perform Housekeep. on 
Args. from Caller 



I 



SETRGN 



Get Coram Region 
Pointers 



Yes. Can't Block 

1 — 




Get a Request Node 
from COMQ Area 



ASGNOO 



Get a Request Node 
from COMQ Area 
(Blk. if Nee.) 



HAVNOD: 



F 

T Pat 



Have a COMQ 
Packet Adr. 



Return"-*^ 

Unsuccessful 
Return 



Store Caller's Args into 

Packet's Fields: 
QINT, QMODE, QCNT, 
QPNTR, QLIN. & QDEV 



DTEQ13: 



Put Unique Code from 
Caller into QCOO 
(For TTYINTs Benefit 
at int. Level) 



OTEQ1: 



Add Packet to End 
ofDTEQS Q. 



•11 



! ucce5sful ( RETSKP) 
Return > — ' . ' 





OTESKD pDTE2 


Idle ^^»fc- 

7 s^ Yes 


Go Start Up the 

DTE 


| No 







DTE1 



Routine to Start a 

/nrcttunS To ' 11 Operation from 
{ DTESKD ? the T<jp of the 0Tg , s 

Driver Queue 




SETRGN 



Get My Comm. Region 
to This -11 



Use Protocol's Vers. No. 
in CMVRR to Pick Up 
Oisp. Adr in SKDVEC Tbl. 




Return ) 



Vector to Dispatch Adr 
& Start Transfer 
(Disp. Adr. - SKVER1 for 
RSX20F Protocol) 



Process Protocol Version 1 



>T— — rv Process Protocol V 
(.SKVER-IJ (RSX20 F) Packets 




(No Formatting 
Needed) 



Set DTE1 1 Bit in DTESTS & 
Active Bit (SNGACT) in Single 
Packet 



If Packet Flushed (QFNC 
Goto 

DEQDTE pDTE4 
to Post Packet & Return 



■0). 



I 



I 



SETRGN 



Get My Comm. 
Region 



From Packet in COMQ Area, 
Setup in PKTAOR: 

HDDEV & HDFNC 
& Clear HDSPR 



I 



Get Single Packet's 
Byte Count 



—j— 

(^^skdm^) 




Store in HDD AT 

MIN[QCNT, MAXINP] 
Set I ndir Bit. DTE 111 in 

DTESTS 
Zero HDUN A 



Store Datum from 
QPNTR into HDOT1 

Set DTE 11 Bit in DTESTS 
(•11 Receiving Bytes) 



STOREG: 



Store t DIOinHDCNT St 
O.LIN (if *0) into HDUN 



STORG1: 


I 




SETRGN 


Get My Comm. 


Region 



I 



Get a Packet Byte 
Count of tD 10 




DTSKDM 



Build 8-Bit Byte Ptr to 
RSX20F Formatted Packet 
Zero CMFWD (I.e., Byte Mode) 



DTSTRT: 



Store Packet's Byte Cnt in 

CMQCT 

Incr. To - 11 Cnt in CM1IC 
Store 8-Bit Byte Packet Ptr.. 

inDTEEBP(in-EPTTbl) 



DINGlT 



Go Start the -11 
(Ring Its Doorbell) 



T 

CRetur 



C INTDTE*) a " Primary Protocol Interrupt! 

N — -'">-—"■-' Com* Here After AC's Are 
Stored by DTETRP Routine 

DTEPRQ: 



DTREST 



Rent the DTE 



DTEPF1 



Tell -11 About 
Power Fail by 
Ringing 11 'i Doorbell 



Dear -11 Done Sit 
by CONO Instr. 



Get Comm. Region 




Dear DTETDN Sit by CONO Instr 



Dismist 
Interrupt 




DODMSO: 



BUGCHK • To 10 
Done Received 
with No Menage 



Get RSX20F's 

Processing Adr., 

DN10RS 




BUGCHK 

DTE Dev Error 



Restore ACi 



, i 1 ■ Dismiss 

CXJENOTETRA) lnwropt 




Reload the Machine 





DTREST 




Reset this 
DTE 


Yes 



Set Reload 
Flag, DTRLD 



Say Mot Running 
a Protocol 

(Clear DTRLD) 



Tell Job Oof 
Reload 

(+1toLOAD11) 



CLRDTE 



Schedule Job 
(+1 toJBOFLG) 



d 



If DTE Inactive & 
DTEQS Not Empty, 
Dequeue & Post 
(Via DEQDTE pOTE4l 
All Requests for this 
DTE 



I 



I Return) 



DTE3 
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To-11 Done Interrupt 



Clear CMIP Bit 
(No Longer Doing 
Indirect) 




' 






TSTSGL 






See if This 
is a Single 
Packet Gp 





OEQDTE 




Dequeue Complet«d Request, 
Post it, & S<:hed. Next Req. 



Put Next Packet on 
Top of OTEQS Queue & 
Get Args from Packet 



("Return ) 



Clear -11's Ptr, DTEEBP 



DN11I 



Set To 11 8it,DTE11 
Store MINl(QCNT),MAXINP) 
into CMQCT 



I 



RLENOD 



Free the Node 



Setup Approp. Byte Ptr 
If a Full Word Ptr., Set 
CMFWD Bit 



NOTWRD: 



I 



Store Byte Ptr. into 

DTEEPP 
Set CMIP Bit (i.e. 

Indir. Ptr. is Set Up) 



I 



DING11 



Go Ring the -11 



( Return j 




OTESKD pOTE2 



Start it 



No, Packet Must 
Be Partitioned 



If QINT#0, 
Vector to its Disp. 
Adr., TTYINT 
pDTE5 



■[ Return) 



Update QCNT by No. 

of Chars. Already Sent 
Adjust Byte Ptr. & Store 

into QPNTR 



DNSNGL 



I 




Return to Post a 
Single Chair. Dona 



OTESKD pOTE2 



Go Do Next 
Part 



Put Next Packet on Top 

of DTEQS Queue 
Clear Single Packet Flag Wd. 



( Return J 



DTESKD pDTE2 



Reactivate the DTE 



Setup 16-Bit Ptr. to 
1st Char, in Packet 



SNGPST: 



I 



For Each Line No., Char Entry 
in the Packet. Pick Up the Line No., 
& With Unique Code - 0, Do the 
Post Via Call to: 

TTYINT pDTE5 



~~ f 

C Return"*^ 



Called at Int. Level to Complete 
a TTY Output Request 
Q TTYtlMT ) (Char*, have been sent" to 

' " ■"'"""■"■ the -11, but not acknowledged) 



I 



GETLIN 



Get Proper 
Line 




f^TTYIN3J 



Get Output Ptr., TTOOUT 
& Advance if Nee. 



I 



CNTSET 



Adjust Output Cnt 



FNOENO 



Go Get Chars. 



DTEQ Failed; 
Restore Cnts. & 
Arrange Sched. to 
Restart Output 



RSCHED 



Update No. of Chars. 

By No. of Chars. Sent 
Store New Cnt in TTOCT 





Add Buf Cnt (TTOCT) 
to Adr. of Dyn. Data. 

Store Orig. Outp. Byte 
Ptr. into TTOOUT 



INTRST: 



TTYIN1 



Add No. of Chars. Sent 
toF.ECntTTFCT 

Clear To-11 Done Pending 
Bit, TTFPK 

Get Line's Allocation 
from TTIFMC 



TTYIN2: 




Store New Output Ptr. 

in TTOOUT 
Get Cnt of Bytes Found 
Get int Disp. Adr <- TTYINT) 
Set Waiting for -11 Done 

Bit, TTFPK 
Store Line's Dyn. Data 

Adr. into TTYVR2 



Oo Single 
Char. 



I 



Clear TTFPK Bit 



Get Args: 
Line No. 

Time Until Event (» 0) 
Disp. Adr. (-TTSN10) 



TTQAD: 



Set Line Waiting For 
Unblock Bit, TTFOW 



T 1 ^ 

(Jjwurnj 

8 i in 



Get Une No., Cnt. & 
String Data; 
[.DFHS0„.FEDLS1 



Compute Time to Do Func. 

for Line & Sav in TTIME 
Save Disp. Adr. in TROUT 
Incr. TTQCNT 
Set Scan Ptr. to this Entry 

if 1st Entry 



Clear Output Active 
Bit.TTQTP 



FIXARGS 



Fix Up the Args 



7*7 

( Return ) 



DTEOpDTEl 



Queue the Request 



Clear Output Active 
Bit, TTOTP & Clean up 



( TTYIN3 ") 



( Return ) 




DTE5 
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-10 Received a 
COINGME) Doorbell interrupt 
| Start to -10 Transfer 



SETRGN 



Gat Comm Region 



BUG INF - 

I3ad Indir. Cnt 




DINGM3: 



BUGINF-To-10 
Cnts Don't Match 



DINGM4 



Sat TO IT Bit in Comm 
Region (CMTOT) (4) 



BUGINF-To-10 
In Progress on 
Doorbell 




1 



Go Reload 








BUGINF-IVs 
Q Count - 







DOFRGM pDTE7 



Start 
Transfer 



c 




DTEDNE 
pDTE3 



Dismiss Interrupt 



DTE 6 



(DOFRGM) 



Routine to Start 
a To -10 Transfer 



SETRGN 



Get Comm 
Region 



I 



Get Protocol Type & 
Dispatch to its "To" 
•10 Xfer Routine 
(Disp. Adr»DOFRRS 
for RSX20F) 



COOFRRS) 

t 



RSX20F Protocol 
To -10 Transfer 



Save Cur. Buf & 
Store Next Buf 
into DTEBF 



I 



(?t"D 



Store Approp. Byte 
Ptr. in DTETBP 



SET2: 



Set Up Approp. Byte 
Ptr. (Full Word (16 Bits) 
or Byte Mode) According 
to CMFWD Bit 



I 



Update Status Word, DTESTS, 
From AC, P2 




Dear DTEBC (No Pending 

Operation) 
Store Q Cnt (Bytes Left) 

into OTEB1 
Get Neg. Wd Cnt & I Bit into 

AC,B 



Set -10 is Receiving 1st 
Frag. Message Bit, DTET1F 
in AC, P2 



I 



Store No. Left for 
Subsequent Reads 
into DTEBC 



I 






I 



Start To - 10 Transfer 
by Sending Contents 
of AC, B, (Via OATAO 
Instr.) Over the DTE 



I 



Sending 
Count 
Over 
the DTE 



C Return ) 



Set Doing -10 Transfer (Last 
Fragment) Bit, DTET10, 
in AC, P2 



If Byte Mode, Get No. 
of Bytes or if Not, Word 
Cnt into AC, B & 
Store Buf Size (in Bytes) 
into DTEB1 




SET1 



DTE 7 
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DNIORS ) P'oca« RSX20F 
• To -10 Done. 




Yn 



OOFRGM pOTE7 



Suit this Fragment 



Otar Intromit Bit 

CMTOT 
G« Cut of Completed 

Req from DTEB1 
Get Cur. Buf from DTEBF 




DODMS1: 



_ 



Make Buf Byte Ptr from 
Adr. in OTBFWO 



Get INCNT 



BUGCHK 

TO10DN - Packet 
Too Small 
<12,) 




Dismisii 
Interrupt 



Clear INVLO 
(Unit in Indir. Word 
it Invalid) 



Save Cnt. in 
Next Packet 
in INCNT 



Oear INCNT 

Find Local Residual 

Cat. 
Get Next Function 



OLDFC1 




No, Done 




Get Packet Size 
& DTE No. 



Ye» (BUGHLT ) 



'Dispatch to Adr. in Tbl\ 
FNCTBL (5) \ 

at Func. Code Offset > 
(OispAdr-TAKLC / 
for DUS tine Chan) / 



f DOFNC3 J 



( TAKLC ) Une Chars (for DLS) 

_T_ 



TAKLC2 pDTE9 



Call Practising Routine 




J 



DTEDN1 



Sat Waiting for Indir. 
Setup Bit, DTI ID 




Indir. Pointer with 
Garbage Packet 



Dismiss 
Interrupt 



DTE8 
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(taklcT) ; 11 Has Sent 

> ■ / Lir 



Line Chars. 




BUGCHK • Odd 
Byte Cnt. for 
Line Chars. 



Get Dev. Type from 
DT1DV & Store into 
SAVTYP 



Yes 



1 



Clear 
SAVOFS 




bughlt) 

Yes Non-TTY Dev. 

on Func. 4 



Get Line Offset 
& Save in SAVOFS 



ISCTY: 



H 



Save Byte Cnt in BYTC 
& Byte Ptr. in BYTP 



TaklcT 



Subtract 2 from BYTC 




(BYTC) > 

' No, Must 
Be At Least 
' Yes Two Bytes 



EftED 



Get Byte, Line No. & Line 
Offset & Type 



I 



DTESTO 



Store in Big Buf. 



( DTESTO ~) Store Char 
n i / in Big Buf. 



Indicate Data is Char for 
TTYBUF by Setting DLSRCF Bit 
Get Dev. Type & Char. 



I 



GETLIN 



Get internal Line 
No. for this Line 




Return 



Line Not 
on F.E. 



J 



Get Internal Line 
No. & Char into AC1 



BIGSTO: 




I 



Dispatch to Tbi. 

TTXXVT 

at Offset 

TTVT22 

F.E. Disp Adr. - BIGST2 

pDTElO 




niPQ 



t RIG sT2 N Ca,,ad fr0m BIGST0 

I WWU J tQ Check Um Ljmjt 

& Store Char. 



No. 

of Chars in 

TTBBUF +1 > 

MAX ABC (-TTBSIZ/2)^ 

? 



Beyond Bad 
Guy Cutoff 



Get Line in AC, C 
Get [.DFTOL„.FEDLS] into AC, B 
Clear AC, A (To the Master) 
Get .DFTLO (Turn it off FuncJ 
into AC, 



Store Updated Cnt. 
in TTFB8 



FIXARG 



Fix Arguments 




SNDXOF 



Send X-OFF 
to Terminal 



DTEOpOTEl 



Output it 



DLSSX1: 



BUGCHK • Big 
Buffer Overflow 




Setup When to Restore 
Line (tOSOOO) 



Iner. in Ptr to 
BigBuf (TTBIGI) 
& Adjust for Wrap 
Around if Nee. 



Dispatch to Table 

rrxxvT 

at offset 

TTVT25 

F.E.Disp. Adr*0LSSX2 



Store AC1 Contents 
into TTBBUF & 
Increment TTBIGC 



TXT 

I Return ) 



/"Z. »«,«« \ BigBuf Has 




Make it a 
Longer Wait 
Time (tD600C 



Get Oisp. Adr. to 
Call TTTOBL 



Decrement Big 
Buf Cnt, TTFBB 



TTOAD: 



Return J 




Compute Time to Do Func 
for Line & Save in TT1ME 

Save Disp. Adr. in TROUT 

Incr. TTQCNT 

Set Scan Ptr. to this Entry 
if First Entry 



{ Return J 



DTE10 
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DTE Interrupt Handling Comments 
TTYINT 



(1) 



OIMGME 



(2) 



(3) 



(4) 



The Unique Code argument of form (0, count) tells 
TTYINT the number of characters that have been sent 
to the -11 in some call to DTEQ that specified 
TTYINT as its return address. 

Count = implies this was a single 
character (DTSNGL was called) 
and buffer counts have already 
been updated. 



Count ?fc implies this 
characters and 
be updated. 



was multiple 
the count must 



TO10IC and T011IC are wrap-around counters of In- 
direct Transfers where TO10IC is maintained by the 
-11 and T011IC is maintained by the -10. If the two 
wrap-around counters are equal , it means the trans- 
fer finished correctly. 

If the difference between the wrap-around counters 
is greater than 1, the -11 has tried to send a 
direct transfer before the last indirect transfer 
finished or a doorbell has been lost in a previous 
transaction. 

Receiver sets TOIT equal to 1 in Sender's section 
of Receiver's communication region after Sender 
sets i? or increments Q count and rings the door- 
bell; Receiver clears TOIT upon getting To-Receiver 
Done (This assures that the Receiver doesn't lose 
an interrupt) . 
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0N10RS 



(5) The function table has dispatches for such features 
as: 

• F.E. telling about the CTY 

• String data for the CDR 

• Line characters (for DLS) 

• -11 Sending error information 

• -11 wants or is sending time of day 

• Line dialed up, hung up or line buffer empty 

• Set line speed or allocation 
•Take -11 reload information 

• Acknowledge all devices and units 

• Take KLINIK data. 
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CHAPTER i 
EXTENDED ADDRESSING IN TOPS-20 



L.l INTRODUCTION 

The Information in this section is of a preliminary nature, and 
should not be construed as a commitment by Digital Equipment 
:orp, TOPS-20 does NOT support user-mode extended addressing at 
:his time. The jsys described herein is available but not 
locumented nor supported. The purpose of this information is to 
Inform the student of the eventual availability of this feature 
:o user mode programs, as we have already learned about the 
jonltor's use of this hardware functionality of the Model B KL 
Processor, 

te Ti B r ?ence8 

DECsystem-iQ/DECSYSTEM-20 Hardware Reference Manual, Vol, 
1 Chapter 3, section 4, page 3-23t Tops-20 
Paging and Process Tables 

telease 4 of TOPS-20 does NOT support user mode extended 
iddressing. Extended addressing is a feature of the current KL. 
Sometimes referred to as "Model B"), with this feature, TOPS-20 
tself will use extended addressing to expand its own address 
ipace. This is true to different extents depending on whether 
:he system is running version 3A or version 4, and also whether 
:he machine is running a 2050 or 2060 monitor, 

!he main purpose of extended addressing is to allow expansion of 
:he previous 18 bit virtual address on the KI, KS and Model A KL 
irecessors to 23 bits. Actually, the software is capable of 
iupporting a processor with 27 bit virtual addresses. The design 
is described herein is intended to support a 30 bit virtual 
iddress space, making our high-end products support larger 
iddress spaces than VAX/VMS. (VAX supports a 30 bit address 
pace as well, but VAX is byte-addressed). Since the code to 
landle the extended capabilities exists within the monitor (for 
he KL), the monitor is the first program built to take advantage 
f the firmware features. 
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The implementation of extended addressing calls for the 
"sectioning" of the large virtual address space. Each section 
contains S12 pages, and corresponds to the traditional 18 bit 
address spaces we are used to. The number of sections available 
depends on the software and firmware capabilities. Current 
support is for the KL, meaning 5 more bits for the section 
number. Therefore, each process can have 32 address spaces eacn 
containing 512 pages. All sections work the same, with the 
exception of section 0, Section references are always in the 
traditional 18 bit format, Non*section references can be local 
or global. With local addressing, instructions executed in that 
section can reference other locations within the section, using 
the same old 18 bit addresses and instruction format as always. 
Global references need to supply a full virtual address, 
including a section number. 



1,1,1 Current implementation Objectives 

The current implementation of user mode extended addressing 
(available but not supported by Digital) intends to provide the 
capability for programs to create and use multiple sections for 
data storage. Also, to allow programs to be run in any section, 
or in multiple sections, with certain restrictions. These 
restrictions are that addresses passed to most Jsys's as 
arguments must specify arguments in the same section as the call 
itself, 



1,1,2 JSYS Interface 

Each section has a page map, and the page maps for a given 
process are pointed to by the process* section map, which exists 
in the User Process Table starting at location USECTB (540), To 
find the page map for section n, we simply look at USECTB plus n, 
where we find a section pointer to the page map, . The Jsys's 
which deal with user mode extended addressing manipulate these 
maps. The SMAP% Jsys sets the map for a section or a virtually 
contiguous series of sections. The 5MAP% Jsys does with sections 
what the PMAP% Jsys does with pages. This includes the 
possibilty of specifying whether the. section is private, shared 
with a file (files don't really have sections, so this specifies 
any group of 512 contiguous pages in the file), or shared with 
some other fork, or some other section within the current fork. 
This indirect relationship is analogous to the indirect mapping 
available on a page basis with the PHAP% call,. This means that 
when the source mapping is changed, the destination will see the 
change in the section's map. 

The RSMAP% Jsys (currently unavailable) will be used to obtain 
information about the current mapping of sections. This 
corresponds to the RMAP% Jsys used to obtain information on pages 
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wl,in a section. Some other Jsys's will be added or changed to 
allow certain functions to occur within the extended environment, 
and usually these have the letter X prefixed to the name of the 
corresponding Jsys. For example, XSIR and XRIR are used to 
specify channel and level tables with full 30 bit addresses, so 
the software Interrupt system can be section independent. Note 
that most Jsys calls which allow the program to supply an 
argument block address will currently not work if executed In a 
non-zero section. 



i,2 PROGRAMMING IMPLICATIONS AND METHODOLOGY 



The basic architecture of the DECsystem-10 family of processors 
up through the KL10 provided an 18-bit, 256K-word addressing 
space. This means in particular thats 

1* The Program Counter register is 18 bitsf 

2. Each and every instruction executed computes an 18-bit 
effective address. The contents. of this address may or 
may not be referenced depending on the actual 
W instruction, but the algorithm for calculating it 
(Including indexing and indirecting rules) is the same 
for all instructions, 

The above is true regardless of the size of the physical core 
nemory available on any particular configuration. Note also that 
aaglng (or relocation on earlier processors) will determine if a 
sarticular virtual address corresponds to an existing physical 
*ord in memory, but the fundamental size of the virtual address 
space is a constant, 

)uring the design of the KL10 processor, the need for a larger 
virtual address space was recognized, A design was developed 
fhich provides an extended address space to new programs while 
still allowing existing unmodified programs to execute correctly 
>n the same processor. Although most of the essential data paths 
*ere provided in the original KL10 implementation, various design 
manges caused actual availability of extended addressing 
>peration as described here to be deferred to the "model B" KL10 

:pu 9 
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1,2.1 Virtual Address Space 

Under the extended addressing design, the virtual address space 
of the machine is now 30 bits, or 1,073,741,824 words. Although 
one can think of this as a single homogeneous space, it is 
generally more useful to consider an address as consisting of two 
components, the section number, and the word number. 

5 6 17 18 35 



11 I J 

• l section i word 1 
» 1 12 bits 1 18 bits J 



The word (more precisely word-within-section) field consists of 
18 bits and thus represents a 256K-word address space similar to 
the single address space on earlier machines. The section number 
field is 12 bits and thus provides 4096 separate sections, each 
of 256K words. 

Each section is further divided into pages of 512 words each just 
as on earlier machines. The paging facilities allow the monitor 
to independently establish the existence and protection of eacn 
section as a unit. 

In order to implement this extended 30-bit address space, the PC 
must be .extended to hold a full address. The PC is always 
considered to consist of a section field and a word field, and 
the incrementing of the PC never allows a carry from the word 
field into the section field. That is, if a program allows flow 
of control to reach the last word of a section and the 
instruction in that location is not a jump, then the PC will 
"wrap-around 1 ', and the next instruction fetched will be word of 
the same section. This will in fact be AC as described below. 
The consequence of this is that flow of control of a program 
cannot inroplicitly cross section boundaries. In general, it 
would be a programming error to allow the PC to reach the last 
location of a section and execute a non-jump instruction or to 
execute a skipping instruction in either of the last -»~ 
locations of a section. 



two 



1,2.2 Compatibility 

In order to allow efficient use of the extended address space, it 
was necessary to modify the operation of various machine 
instructions and to change the algorithm for the calculation of 



COPS-20 Monitor Internals Page 1-5 

PROGRAMMING IMPLICATIONS AND METHODOLOGY 



iff ctive addresses. Because these changes have a high 
srWability of causing any existing program to malfunction, the 
following convention was adopted: 

If a program is executing in section 0, all 
instructions are executed exactly as they 
would be on a non-extended machine. If a 
program is executing in any section other 
than o, the extended addressing algorithms 
are , used for effective address calculation 
and instruction execution. 

V program is said to be executing in section when the section 
field of the PC contains 0, Effective address calculations and 
Instruction executions are performed exactly as on a non-extended 
lachine; hence any existing program will work correctly if run 
.n section 0, Note however, that this also implies that no 
iddresses outside of section can be generated, either for data 
'eferences or for Jumps, That is, a program executing in section 
» cannot leave section except via a monitor call. The only 
exception to this is the XJRSTF instruction, 

:t is easy however to write or generate code which is compatible 
rith both extended and non-extended execution. This was a 
ipecific goal of the design, and in general requires only that 
:ertain precautions must be taken regarding previously unused 
:li_Js, Since these precautions must be taken however, one 
ranffot generally assume that any existing program will have 
ibserved them and so execute correctly In an extended section. 



,2,3 Effective Address Calculation 

inless explicitly stated otherwise, everything In the following 
liscussion refers to execution of instructions with the PC in a 
ion-0 section; nothing applies to instructions executed from 
lection 0, 

i. Instruction format 

The format of a machine Instruction is the same as on a 
non-extended machine. In particular, the effective 
address computation is dependent on three quantities 
from the instruction, the ¥ (address) field, the X 
(index) field, and the I (indirect) field. These are 18 
bits, 4 bits, and 1 bit respectively. 
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J 
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Depending on tne format of the index and indirect words, 
the effective address algorithm will perform either 
18-bit or 30-bit address computations. When a 30-bit 
quantity is indicated, an explicit section number is 
being specified and the address is called a global 
address. When an i8-bit quantity is indicated, the 
section field is defaulted from some other quantity 
(e t g,, the PC), and the address is thus local to the 
default section and is called a local address, 

in the simplest case, consider an instruction which 
specifies no indexing or indirection, E,g,, 

3, ,400/ MOVE T,1000 

Here the effective address computation yields a local 
address 1000, and the section used for the reference is 
3, i.e., the section from which the instruction itself 
was fetched. Precisely stated: 

Whenever an instruction or indirect word specifies 
a local address, the default section is the 
section from which the word containing that 
address was taken. 

This means that the default section will change during 
the course of an effective address calculation which 
uses indirection. The default section will always be 
the section from which the last Indirect word was 
fetched. 



2, Indexing 

The first step in the effective address calculation is 
to perform indexing if specified by the instruction. 
The calculation performed depends on the contents of the 
specified index register: 

1, If the left half of the contents of X is negative or 
0, the right half of X is added to Y (from the 
instruction word) to yield an 18-bit local address. 

This is consistent with Indexing on a non-extended 
machine, and means, for example, that the usual 
A0BJN and stack pointer formats can be used for 
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tables and stacks which are in the same section as 
the program, 

2, If the left half of the contents of X Is positive 
and non-0, the entire contents of X are added to Y 
(sign extended) to yield a 30-bit global address* 

This means that index registers may be used to hold 
complete addresses which are referenced via indexed 
Instructions, A Y field of will commonly be used 
to reference exactly the address contained in X* 
Small positive or negative offsets (magnitude less 
than 2**17) may also be specified by the Y field, 
e,g», for referencing data structure items in other 
sections. 



3, Indirection 

If indirection is specified by the instruction, an 
indirect word is fetched from the address determined by 
Y and indexing (if any). The indirect word is 
considered to be "instruction format" if bit is a 1, 
and "extended format" if bit is a 0, 
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2, Extended Format Indirect Word (EFIW)s This word 
contains Y, X, and I fields also, but in a different 
format such as to allow a full 30-bit address field. 



12 5 6 17 18 35 

I'll i S 

10 J ii X J (section) 1 Y (word) I 

1 1 1 i l I 
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If indexing is specified in this Indirect word, the 
entire contents of X are added to the 30-bit Y to 
produce a global address, A local address is never 
produced by this operation, and the type of 
operation is not dependent on the contents of X, 
Hence, either Y or CCX) may be used as an address 
or an offset within the extended address space just 
as is done in the 18-bit address space. 

If further indirection is specified, the next 
Indirect word is fetched from Y as modified by 
Indexing if any. The next Indirect word may be 
Instruction format or extended format, and its 
Interpretation does not depend on the format of the 
previous Indirect word, 

4, Some examples 

1, Simple instruction reference within the current PC 
section: 

3,, 400/ MOVE T,1000 i/fetches from 3001000 
JRST 2000 ;jumps to 3002000 

2, Local tables may be scanned with standard AQ8JN 
loops i 

MOVSI X,-SIZ 
LPl CAMN T,TABL(X) ;TABL in current section 
JRST FOUND 
AOBJN X,LP 

3, Global tables may be scanned with full address and 
index; 

MOVEI X,0 
LPl CAMN T,@EEFIW TABL,X] /TABLCX) in ext 
fmt 

JRST FOUND 

CAIGE X,SIZ-1 

AOJA X,LP 

4, Subroutine argument pointer may be passed to 
subroutine in another section: 

word in arglist: 

IFIW &VARCX) ;lndexing and indirecting 

/if specified will be relative 
;to the section in which this 
/pointer resides, i.e., the 
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jsection of the caller 



1,2.4 Immediate Instructions 

ill effective address computations yield a 30-bit address 
defaulting the section if necessary, as described above, 
Cmmedlate instructions use only the low-order 18-blts of this as 
:heir operand however, setting the high-order 18 bits to 0, 
ience, instructions such as MOVEI, CAI, etc, produce identical 
results regardless of the section in which they are executed, 

Pwo immediate instructions are implemented which do retain the 
section field of their effective addresses, 

1, XMOVEI (opcode 415) Extended Move Immediate! 

This instruction loads the entire 30-blt effective 
address into the designated AC, setting bits 0-5 to 0, 
If no indexing or indirection is specified, the current 
PC section will appear in the section field of the 
result. This instruction would replace MOVE! in those 
w cases where an address (rather than a small constant) is 
being loaded, and the full address is needed. 

Example: calling a subroutine in another section 
(assuming argllst in same section as caller)! 

XMOVEI AP,ARGLIST 

PUSHJ P,9CEFIW SUBR] 
The subroutine could reference arguments ass 

MOVE T,91(AP) 
or could construct argument addresses byt 

XMOVEI T,92(AP) 

In both cases, the argllst pointer would be found in the 
caller's section because of the global address in AP, 
The actual section of the effective address is 
determined by the caller, and is implicitly the same as 
the caller if an IFIW is used as the argllst pointer, or 
is explicitly given if an EFIW is used, 

w 2, XHLLI (opcode 501) 

This instruction replaces the left half of the 
designated accumulator with the section number of its 
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effective address. It is convenient where global 
addresses must be constructed. 



1.3.5 AC References 

Any reference to a local address in the range 0-17(8) will be 
made to the hardware ACs. Also, any gobal reference to an 
address in section 1 in the range 0-17(8) (i,e., 1000000-1000017) 
will be made to the hardware ACs. Global references to locations 
0-17(8) in any section other than section 1 will reference 
memory. Thusi 

1. Simple addresses In the usual AC range will be reference 
ACs as expected, e.g., MOVE 2,3 will fetch from hardware 
AC 3 regardless ot the current section, 

2, To pass a global pointer to an AC, a section number of i 
must be included. 



3, 



Very large arrays may lie across section boundaries; 
they will be referenced with global addresses which will 
always go to memory, never to the hardware ACs, 



4. PC references are always considered local references; 
hence a Jump instruction which yields an effective 
address of 0-17 in any section will cause .code to be 
executed from the ACs, 



1,2,6 Special Case Instructions 



In addition to the differences in effective address calculation, 
certain instructions are affected in other ways by extended 
addressing. 



It 



2, 



Instructions which store/load the PC; PUSHJ, POPJ, JSR, 
JSP. These instructions store a 30-bit PC without flags 
and with bits 0-5 of the destination word set to 0, 
POPJ restores the entire 30-bit PC from the stack word, 
JSA and JRA are not affected by extended addressing and 
store/load only 18 bits of PC, Hence they are not 
useful for inter-section calls, 

Stacle Instructions (PUSHJ, POPJ, PUSH, POP, ADJSP) use a 
local or global address for the stack according to the 
contents of the stack register following the same 
convention as for indexing. That is, if the left half 
of the stack pointer Is or negative (prior to 
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w incrementing or decrementing), a local address using the 
right half of the stack pointer is computed and used for 
the stack reference. If the left half of the stack 
pointer is positive and non-0, the entire word is taken 
as a global address, In the latter case, incrementing 
and decrementing of the stack pointer is done by adding 
of subtracting 1, not 1000001, Hence, a global stack 
for routines in many sections may be used in a similar 
manner to present stacks. Stack overflow and underfow 
protection would be done by making the pages before and 
after stack inaccessible since a space count field is 
not present in a gobal stack pointer, 

3, Byte instructions. Two formats of byte pointer are 
recognized by the byte instructions. The non-extended 
format is identical to the present standard byte pointer 
format and is recognized if bit 12 (previously unused) 
is 0, If bit 12 is 1, a two-word extended byte pointer 
format is recognized which contains the fields as shown? 
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Note that the second word is identical to the Extended 
Format indirect Word (EFIW), The right half of the 
first word is specifically reserved to software for byte 
counts, etc. Incrementing of this format of byte 
pointer .is consistent with non-extended format? the P 
field is reduced until the end of the word is reached, 
whereupon the address in the second word in incremented. 
Incrementing may cause a carry from the word field to 
the section field of the address? hence extended byte 
arrays may lie across section boundaries, 

4, Other new or modified instructions are LUUOs, BLT, XBLT, 
XCT, XJRSTF, XJEN, XPCW, XSFM, Some of these are valid 
only in exec mode. Consult the System Reference Manual 
or chapter 2,2 of the KL10 Functional Specifications for 
details. 
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1,2.7 Compatible Programming 

It is possible to generate code which works correctly in both 

extended and non-extended environments. Such code may even 

utilize inter-section references when running in an extended 
environment! it is not limited to local addressing. 

The basic rule is to observe the extended addressing rules in the 
construction or computation ofi 

1, Index wordsi be sure the left half is cleared or 
contains a negative quantity (e.g., a count) when 
setting up and using an index register. This will cause 
a local reference in the extended environment which will 
produce the same result as on the non-extended machine. 

2, Indirect wordsi always set bit of indirect words used 
in argument lists, etc, so as to produce local 
addresses, 

3, Stack pointers: the most common present format 
(negative count in left half) works consistently under 
extended addressing; modifying a program to use an 
extended stack should require no change to stack 
instructions except if the code expects to find the 
processor flags in the stacked PC words. 

When generating addresses to be passed to subroutines or used by 

other code, XMOVEI and XHLLI instructions may be used. In the 

non-extended environment, these opcodes are SETMI (equivalent to 

MOVED and HLLI respectively, which always load into the left 
half. 



1,2,8 Program Architecture And Facilities 

Ultimately, the extended addressing hardware in conjunction with 
the monitor should provide some of the power of general 
segmentation and some other useful conventions and facilities. 
The following are some of the ideas which have been advanced, 

1, The fact that instructions are generally executed 
relative to the current sections suggests that 
subroutine libraries and facilities packages can be 
written which can be dynamically loaded into any 
available section and used by many programs. An 
important point to observe in connection with this and 
most of the following conventions is that programs must 
not be compiled with fixed section numbers built into 
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the code. Programs should be built so as to be loadable 
into any section and to request additional section 
allocations from the monitor as necessary. This is the 
only reasonable way to ensure that conflicting use of 
particular sections is avoided, 

2, An entire section can be mapped, by the monitor as 
quickly as a single page. Hence, an entire file Cup to 
256K) can be napped into a section, and the data therein 
manipulated with ordinary instructions, 

3, Programs can greatly reduce memory management logic by 
merely assuming very large sizes for all data bases, . It 
is not however, very efficient to use many sections, 
each with only a small amount of data. A reasonable 
middle ground should be chosen. 



CHAPTER 2 
BIAS CONTROL 



.1 BUS C0MI80L 

he bias control Knob provides for administrative control over 
ome scheduling algorithms. The Knob allows a system 
dminlstrator to bias the system according to the needs of the 
nstailatlon, to establish degrees of "fairness* among 
ntractive and compute-bound users. This logical knob has 
eCTfings from I to 20, The lower the setting of the Knob, the 
ore interactive jobs are favored. The higher the setting of the 
nob, the more compute»bound jobs are favored, 

10 11 
9 **** 12 

* * 

♦ * * 

5 * * * 15 

* * * 

* * * 

* * * 

nteractlve 1 *. ** * 20 compute 

**************************** 

Figure of the bias control Knob 

Figure 
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2.1.1 USER INFORMATION 

The bias control Knob can be set through the use of a command to 
OPR f the operator interface. The command has the form* 

OPR>SET SCHEDULER BIAS-CONTROL (to) n 

where n is a decimal number from 1 to 20, 

The bias knob can also be set through the use of a CONFIG 
command. The following command can be placed in 4»C0NFIG,CMD: 

BIAS n 

where n is a decimal number from 1 to 20, 



2,1.2 PROGRAMMING INFORMATION 

Bias control can also be changed under program control through 
the use of the new SKED% JSYS. The ,SKRBC function of this JSYS 
reads the bias control Knob setting; the .SAKNB function sets 
the bias control Knob setting. 



2.1.3 IMPLEMENTATION 

The value of the bias control Knob is a displacement into a table 
of twenty entries. Each table entry represents a set of binary 
switches controlling a scheduler algorithm. Any binary value 
that causes an "on" setting CD causes a bias in favor of 
interactive jobs while any binary switch that is "off" CO) Is 
biased in favor of compute-bound jobs. 



2,1,4 SWITCH SPECIFICS 

The following is a graph of the current table Cwhich starts at 
location SKFLGV) being used for the bias control Knob, 
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Graph of Bias Settings 
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The following describes the current switches and their actions: 

SK%CYT Bit 18, default setting is on. 

Used for adjusting the length of the cycle times for the 
short and long cycle clocks. If i# standard values for the 
cycle times are used (20 ms and 100 ms). If 0, the cycle 
times used are four times the standard cycle times (80 ms 
and 400 ms). This switch favors compute-bound jobs if off, 
since longer cycle times should reduce overhead, interactive 
jobs may not be allowed in during the longer cycles (they 
wait longer to be chosen), and a corapute-bound job can hold 
the processor longer during longer cycles (which reduces 
context switching), 

SKIIOC Bit 19, default setting is off J does not change, 

Used to decide if a fork's quantum time should receive a 
charge for I/O, This is not really a bias between 
interactive and compute-bound processes in the strict sense. 
Jobs that do a large amount of disk file I/O are affected. 
Off indicates the charge is to be made; on eliminates this 
charge, 

SK%HT1 Bit 20, default setting is on. 

The SK%HT1 switch controls the number of processes with 
balance set hold time. If the switch is on, there is no 
more than one other process with balance set hold time, and 
less than half of memory is allocated, the process under 
consideration is given hold time. If the switch is off or 
the other conditions do not hold, the process is given hold 
time. The switch favors interactive processes if on by 
controlling the amount of hold time for!a process. This 
keeps the balance set membership more dynamic which helps 
interactive processes back into the balance set, 

SK%HT2 Bit 21, default setting is off. 

If on, a process that enters the balance set after a process 
of higher priority has been skipped receives no balance set 
hold time. This favors interactive processes by not 
allowing processes of lower priority to run for long periods 
when processes of higher priority cannot fit into the 
balance set, 

SK%HQR Bit 22, default setting is off, 

used to control "HQ disaster avoidance," If, during system 
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operation, the load average reaches a certain level Ca load 
average between 4 and 6) low queue jobs (which tend to be 
compute-bound jobs) are no longer allowed into the balance 
set. If the load average goes higher (to between 6 and 9) 
low queue jobs are forced out of the balance set. If this 
switch is off, the code that causes the above to happen is 
skipped. Having this switch off favors compute-bound jobs 
since they can still get machine time when the load average 
is high, 

Hts 23 and 24 are currently not used. 

(K%RSQ Bit 25, default setting is on. 

The SK%RSQ switch determines whether an overhead cycle is 
initiated when a process with higher priority than the 
running process becomes runnable as the result of disle I/O 
completion. If the switch is on and the conditions are met, 
the current process is dismissed and the higher priority one 
selected to run during the overhead cycle. This favors 
interactive processes since they can be run Immediately 
after unblocking. If tne switch is off, the dismissal 
^ occurs in the next normal overhead cycle, 

KlRQi Bit 26, default setting is on, 

used for controlling the use of the Interactive queues. If 
this switch is off when setting the queue level for an 
unblocking process, the interactive queues are not used. 
This favors compute-bound jobs if this switch is off since 
the interactive jobs do not get the increased priority and 
the extra quantum of the interactive queues, 

K%TTP Bit 27, default setting is on, 

used to control the moving of processes to the Interactive 
queues for TTY wait. If on, the added boost of moving the 
process to Ql is given, which favors interactive processes 
with an increased priority, 

K%WCF Bit 28, default setting is off. 

Used to decide whether to decrease the wait credit of a 
previously blocked process based on the load average in 
determining the new queue. When off, the wait time is 
^divided by the short-term load average to maintain fairness 
(that is, decrease the advantage gained for a wait if the 
load average is high>, other processes on the system have 
not fared that well while the process was blocked. When on, 
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interactive jobs are favored since they are not penalized 
for a high load average. 

Bits 29 to 35 are not used. 

It is interesting to see how values change from one setting of 
the knob to the next. Some changes of the knob may cause no 
change in the scheduler. For example, changing the Knob from 1 
to 4 currently causes no change in the scheduler. Changing from 
16 to 17, however, causes three specific switches to be changed. 
Also, notice that the design of the table lends itself to changes 
in the future. 



CHAPTER 3 
CLASS SCHEDULING 



.1 CLASS SCHEDULING 

lass scheduling enables the administrator of a system to 
llocate the system according to classes of users, 

n a particular system there may be classes of users that need 
arge amounts of resources at a given time, There may also be a 
li^J of users that should not be given a large amount of 
esTurees, Class scheduling permits the administrator of a 
ystem to allocate system resources (specifically, CPU resources, 
hich implies other resources such as I/O and memory) on the 
asis of class. 



NOTE 

Class scheduling is not required. 
If it is not enabled, its 
parameters are ignored, 

onslder the following example: 

DECSYSTEM-20 is used for computer courses at a university, 
his system has three definite classes of usersi 

1, students that are talcing the computer science courses 

2, Faculty members that give the courses 

3, Administrative users that do some processing during free 
time on the machine 

*Wy wish to divide up the machine as shown below: 
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Figure 2-3 

Using class scheduling, the administrator would define three 
classes on the system, Each class would be defined to receive 
the indicated percentage and each user would be assigned to a 
class. 

An important point should be realized concerning the divisions 
made in the example above. The machine is divided using class 
scheduling. If there is one student, three faculty members, and 
five administrators on the machine at a given time, the system 
would try to give the one student 75% of the machine, each of the 
faculty would receive 5% of the machine, and each of the 
administrators would receive only 2% of the machine. Or, another 
situation might have 25 students and only one member of the 
faculty and administrative groups at a given time, In the latter 
case, even though the students were allocated a larger percentage 
of the machine, each student would receive only 3% while the 
faculty user and the administrative user would receive 15% and 
10%, respectively. It is therefore important to consider the 
size of a class of users when defining the percentage of the 
machine for that class. 

As in the case where one student was logged on the system, it is 
possible that a particular class may sometimes not be able to use 
all of its allocated percentage. The amount of unused CPU 
resource in such a case is Known as nindiall. Another possible 
case that creates windfall is when all of the machine is not 
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allocated with class percentages. In either case, windfall can 

se either withheld or allocated. If withheld, the system runs 

Ldle rather than give a class more than its share. If windfall 
Ls allocated, the system distributes the excess CPU resource 
proportionately among the active processes. 



NOTE 

withholding of windfall ls not 

recommended. Its use should be 

restricted for at least two 
reasons: 

1, If withholding windfall is 
enabled before all of the class 
percentages are defined 
correctly, a condition could 
exist where no one could do any 
useful work, 

2, It wastes system resources. 



1,1.1 USER CHARACTERISTICS 

'he first step in implementing class scheduling Is to determine 
rhether it ls really needed. Class scheduling should aot be used 
inly because it is there. There should be a definite need for 
lividing up the machine. It is important to remember that while 
:lass scheduling may improve throughput for a particular class, 
.t probably decreases throughput for the system as a whole, 
!here is overhead involved with class scheduling and for this 
eason its use is not recommended with small machines (2020s and 
!050s with less than 2S6K), It is not that class scheduling does 
lot work with these machines — the expense in overhead of using 
:lass scheduling on small machines probably outweighs the 
•osslble benefits. 



,1,2 CLASS ASSIGNMENT 

m^a need is established to use the class scheduler, the class 
lemfers must be identified and assigned. Identifying the members 
equires grouping them according to characteristics. Assigning 
sers to a class on the system requires using one of two 
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available methods. 

To Identify the classes requires some considerations of the 
mechanisms that the system uses. The system only supports eight 
classes, each specified on the system with a number from to 7. 

The characteristics of a class can be determined in a number of 
ways. In the previous example, the groupings were based on the 
obvious distinctions between students, faculty, and 
administrators. In the case of a timesharing bureau, the 
divisions could be made based on specific customers, with the end 
result being the sale of specified portions of the machine. 

After the classes are defined, they need to be assigned on the 
system, There are two methods for accomplishing this. 

The recommended method of assigning class members is to use the 
accounting system. Using this method, class membership becomes 
an attribute of a particular account. As the user logs in and is 
assigned an account, the user is also placed in the class that is 
identified as an attribute of that account. If the user is able 
to change accounts with the SET ACCOUNT command, the action of 
changing accounts may also change the class of the user. 

NOTE 

Using the accounting method 
requires that account validation be 
enabled. 



An alternate method of assigning class membership Is to use the 
access control job, By using this method, the user's class can 
be determined dynamically by a user-written policy program. This 
enables class assignments to be based on the current state of the 
system, 

If the class is not assigned by one of these methods, the system 
assigns a user to a default class as the user logs in. 



3,1.3 CLASS PERCENTAGES 

The next step in implementing class scheduling Is to determine 
the class percentages. The number of members in the class needs 
to be considered. As seen previously, the more members of a 
class with active jobs on the system, the less the percentage 
each member of the class receives. Factors unique to the 
Installation, such as time as day, need to be considered. In the 



roPS-20 Monitor Internals Page 3-5 

:lass scheduling 

!nli*ersity example, students may receive a very large percentage 
>£ the machine during the day, when they are doing a majority of 
;heir work. At night, however, the administration may need a 
.arge percentage of the machine for administrative work, 

'inally, the mechanics of the implementation need to be 
:onsidered. In assigning percentages to classes, the total 
•ercentage can be less than 100 % of the machine but not more 
han 100 %, 

'he percentages for classes can be defined in one of three ways; 
y using CONFIG commands, by OPR commands or by a policy program, 

define the class percentages using CONFIG commands, a command 
t the following form must be placed in 4-CQNFIG,CMDt 

Create n frac 

where: n is the class number (0-7), 

frac is the class percentage expressed as a 
fraction of 1 (0,00-, 99), 

here should be as many CREATE commands as there are classes on 

he system, 

o%€flne the class percentages using OPR commands, a command of 
he following form must be used: 

opr>set SCHEDULER CLASS (number) n (to percent) per 

where: n is the class number (0-7), 

per is the class percentage (0-99) 
(note that per is actual percentage in 
this case), 

fiis command enables the operator to change class percentages 
aring normal system operations, 

le class percentages can also be changed using a policy program, 
sis enables the percentages to be changed dynamically as based 
i administrative policy. 



.1,4 Batch Class 



>r added control of batch jobs, the administrator can require 
i S«' batch :Jobs be Placed in a specific class on the system, 
sing this option, batch jobs are placed in the specified batch 
Lass, This overrides the class assignment that would be 
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received if the user were to log in normally. This option is 
indicated either through a CONFIG command, an OPR command, or 
through the use of a policy program. 

NOTE 

This option requires class 
scheduling to be implemented using 
the accounting method. If the 
classes are assigned with the 
policy program, the batch class 
commands have no effect. 



The CONFIG command has the formt 
BATCH-CLASS n 
where n is the class to be used for batch jobs (0-7), 

The OPR command has the forrai 

OPR>SET SCHEDULER BATCH-CLASS n 

where n is the class to be used for batch jobs (0-7), 



3,1.5 TURNING CLASS SCHEDULING ON/OFF 

Class scheduling can be turned on and off using either CONFIG 
commands, OPR commands, or a policy program. The CONFIG and OPR 
commands are described below. 

Starting class scheduling with a CONFIG command requires two 
additional pieces of Information, First, the disposition of the 
windfall must be determined by the requirements of the system. 
For example, if the requirements are such that no user is to 
receive more than his allocated share, windfall should be 
withheld. 



NOTE 

If windfall is withheld and there 
are errors in the CONFIG file, a 
situation could occur where no one 
has processor time allocated to 
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them. 



Second, the method for determining class assignments, either by 
iccounting or by policy program, should be identified. The 
:ONFIG command has the form; 

ENABLE CLASS-SCHEDULING ACCOUNTS WITHHELD 

POLICY-PROGRAM ALLOCATED 



NOTE 

This command must be the last class 
scheduling command in the CONFIG 
file. That is, it must follow all 
of the CREATE and BATCH commands. 
If it does not, all CREATE or BATCH 
commands that follow the ENABLE 
command will have no effect. If 
windfall is withheld and all of the 
CREATE commands follow the ENABLE 
command, no class will have 
percentages and no one will be able 
to do any useful work. 



!he OPR command for starting the class scheduler requires the 
same information that the CONFIG command requires. Both the 
tethod for assigning classes and the disposition of the windfall 
ihould be indicated. The OPR command has the forms 

opr>enable class-scheduler 

/class-assignments: accounts 

policy-program 
/windfall! allocated 
withheld 

iPR has an additional command for disabling the class scheduler: 
OPR>DISABLE CLASS-SCHEDULER 



,1.6 IMPLEMENTATION 

lr~% scheduling is used to influence the priority of a process, 

^*p**ocess that is ahead of its percentage will tend to have its 

riority reduced and a process that is behind its percentage will 

end to have its priority increased, Therefore, a process* 
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relation to Its "target" percentage is a new metric that becomes 
part of the heuristic that dictates the transition rules among 
the queues. The following is a description of the new metrics 
and how they are employed, 

A Job's "utilization" is periodically computed by the process 
controller as a decaying average of the CPU time used by the 
processes of the job. The computation performed is 

U(I+13*UCl)*e*C-t/C)+FCt-e*(-t/C)) 
wherer UCI) is the current process utilization. 

F is the fraction of the CPU used by the process in the 
recent Interval "t", 

t is the time since the last computation of U, 

C is the "decay" interval. After time C, the utilization 
decays by e. This number represents the amount of 
"history" that the monitor uses in determining a process* 
behavior. The number is chosen to insure as uniform a 
behavior as possible. 

The utilization function for each of the classes is the sum Of 
the utilizations of the jobs in the class. The class 
utilization, CU, is used to compute the class "distance" CCD) 
from Its ideal (target) utilization as follows: 



CP - CU 

CD s ..— — — < 

CP 



where* CP is the class' ideal utilization, CP is the class 
percentage assigned when the class is defined. 

Each Job also has a job distance CJD) calculated as follows* 

CP 

N 

CP 

N 

where* JU is the job utilization, 

N is the "population" of the class of which this job is 
a member, N is currently the number of logged-in jobs 
belonging to the class, 

The class distance and the job distance serve as a two-Key sort 
for the GOLST for assigning priorities, CD is the primary key 
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snVjD is the secondary Key, In addition to this sorting, 
"specials" in the assigning of priorities ensure that certain 
rriticai and interactive processes are scheduled promptly (for 
sxample, NOSKED, CRSKED, high priority queue processes). 



CHAPTER 4 
EXECUTE-ONLY 



•1 EXECUTE-ONLY 

xecute-only provides the capability of protecting files from 
eing changed or examined, while allowing the same files to be 
xecuted. 



,1.1 OEEiilXlXOM 

n execute-only file is One that cannot be copied or read in a 
ormal manner, but can be run as a program. In order to provide 
his in TOPS-20, the following constraints must be placed on a 
lie in order for it to be considered an execute-only fliei 

1, The file must be protected with EXECUTE access allowed 
but without READ access allowed, 

2, The file cannot be read or written using any of the 
file-oriented monitor calls (i,e,, SIN, SOUT, BIN, PMAP 
in referencing a file, etc,), 

9, The file can be mapped into a process (via GET5 , but 
only in its entirety and only into a virgin process, 

n execute-only process is a process that is created by 
erforming a GET on anexecute-only file. To insure security for 
he execute-only file and process, the execute-only process must 
Iso be restricted* 

^^l. No other process can read from an execute-only process* 
address space or accumulators. 



TOPS-20 Monitor Internals Page 4*2 

EXECUTE-ONLY 

2* No other process can change any part of an execute-only 
process' context In such a way as to cause the 
execute-only process to reveal any part of Its address 
space unintentionally* 

3, An execute-only process must start at either its START 
or REENTER entry point (ENTRY VECTOR). Allowing a 
process to start elsewhere could cause it to reveal 
itself, 

4. An inferior for* that is created from an execute-only 
process with the same map should be execute-only also* 

Some related definitions are 

Virgin process — A process that has just been created (using 
CFORK) with none of its pages having been mapped and no 
operations having yet changed its context. 

Context of a process — The context of a process includes its 
address space, PC, ACs, interrupt system, traps, etc, 



4.1.2 USES CHAaACIEBISXICS 

An execute-only file is created by modifying the protection 
attribute of the file. This can be done by setting the 
protection field for the the desired class of users (owner, group 
or world) to FP%Ex+FP%DIR, or 12 (octal). For example, to make a 
file execute-only for everyone except the owner of the file, set 
the protection to 771212, This indicates that the file can only 
be seen with the directory command and executed; the file cannot 
be read or written, 

NOTE 

Any file can be made execute-only. 
This can include data files, for 
example, but the results of such an 
exercise prevents any use of the 
file. It does tiQI indicate that 
the file can only be read by an 
executing process. 



An execute-only process is created by performing a GET on an 
execute-only file — using a virgin process* address space. This 
prevents merging the execute-only file into an address space 
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>h?Wh may already contain code that could reveal the address 
pace of the execute-only file. 



,1,3 WHAT CAN AND CANNOT BE EXECUTE-ONLY 

ue to the characteristics of execute-only, there are some 
estrlctlons as to where it can and cannot be used, 

ost programs C.EXE files) can be protected execute-only. For 
xample, saved COBOL, FORTRAN, and BASIC programs can be 
xecute-only. Some utilities that can be execute-only includes 
UMPER, TV, EDIT, etc. 



NOTE 

Although COBOL and FORTRAN programs 
can be made execute-only, care must 
be exercised. The object time 
system (0T5) must be included in 
the EXE file. Otherwise, users can 
roaice their own "OTS" and define 
SYS* to cause that OTS to be used 
and to cause the execute-only 
process to reveal itself. 



here are some programs that cannot be execute-only. Some of the 
ajor ones are listed here along with an explanation of why they 
annot be execute-only: 

1, Any object time system such as FOROTS — These are 
merged into an address space. This violates the 
restriction that confines the reading of an execute-only 
file into a virgin address space. Notes This does not 
imply that an execute-only process cannot bring in an 
OTS, but only that the OTS cannot be execute-only, ^ 

2, The TOPS-10 Compatabliity Package (PA1050) — :. This 
cannot be execute-only for the same reason that an OTS 
cannot, 

3, Any program that is brought in with the TOPS-10 UUO's 
RUN and GETSEG — These UUQs require the program to be 
mapped into nonvirgin address space. 
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4, Any program that needs to be started at any location 
except its entry vector (START or REENTER address) — To 
start elsewhere may cause an execute-only process to 
reveal itself. 

5, Any program that uses TOPS-iO-style "CCL starts" 
(starting at the start address plus one) « Again, the 
program cannot start at a location other than that 
specified in the entry vector, 

6, A compiler or linker invoiced through the 
C0MP1LE/LOAD/EXECUTE/DEBUG commands « These use the CCL 
start. 



4.1,4 SOME OTHER RESTRICTIONS ON THE USER 

Some other restrictions on using an execute-only file or process 
are extensions of the previous definitions, 

EXAMINE, DEPOSIT, MERGE, DDT, SET ENTRY-VECTOR, SET PAGE-ACCESS, 
SET ADDRESS-BREAK commands do not work for execute-only 
processes. These commands would either cause the process to 
reveal Itself, or allow a modification to the process that could 
eventually cause the process to reveal itself. 

The START command cannot be used with a start address argument 
for an execute-only process. The process must be started using 
its defined entry points (entry vector). 

The INFORMATION (ABOUT) VERSION will only return the name of the 
program. The version information is part of the process address 
space that is not to be revealed. 

It is important to note that the use of execute-only protection 
does not guarantee the security of the file. It is the 
programmer's responsibility to insure that the program does not 
reveal itself through programming mistakes that would, for 
example, allow the program to map itself to unsecured forks or 
use noncertified libraries. 

WHEEL privileges can affect the use of execute-only files. An 
enabled WHEEL cannot create an execute-only process. It is when 
the process is initialized that it becomes execute-only. If the 
user has WHEEL privileges and they are enabled, the execute-only 
code in the initialization is bypassed since the enabled WHEEL 
has read access as well as execute access. For a user with WHEEL 
privileges enabled to create an execute-only process, privileges 
must first be disabled, the GET performed, and the privileges 
reenabled if needed. 
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>.1.5 IttekfittEUXAllOti 

'he Implementation of execute-only involves some data In the JSB, 
'hecks In a number of JSYSs to see If the user Is allowed to 
xamine a particular process, and steps in a few JSYSs to set up 
xecute-only processes* 



,1.5.1 DATA STRUCTURE 



n the JSB is a SYSFK area that has an entry for each process of 
he job, Three flags contain information about the process 
eeded for execute-only. An entry appears as followss 



12 3 4 



8 9 



17 18 



! 1 



35 



I 

•+ 



4ta 



eaiafces 



Content* 



-17 
8-35 



SFEXO 
SFNVG 
SFGXO 



FKHCNT 



if set, indicates entry not in use, 

fork has been deleted 

If set, fork is execute-only 

If set, fork is not virgin 

If set., indicates fork can pmap into 

execute-only forks because it is doing 

an execute-only GET 

Not used 

Count of handles on a given fork 

System fork number 



,1,5,2 ROUTINES - 



ost of the use of the flags in the SYSFK area described above 
akes place in general routines. These routines are described 
elow, 

hkmxs - CHecK if Not execute-only or Self — Routine CHKNXS Is a 
eneral test routine to determine if the process specified is 
ither SELF or not an execute-only process. Otherwise, an 
llegal Instruction trap occurs, returning the error FRKHX8 — 
Illegal to manipulate an execute-only process", if the 
Pt .fled process is not execute-only, it will be declared 
onTIrgin by clearing the virgin process bit SFNVG, 

ETEXO - SET process EXecute-only — This routine in FORK will 
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cause the selected process to become execute-only. If the 
process Is not virgin, this does not succeed. 

SETGXO/CLRGXO - SET/CfceaR GET eXecute-Only status — These 
routines set and clear the execute-only GET bit (SFGXO) in the 
current process. These routines are called by GET to allow 
mapping into an execute-only process, 

CLRVGN - CLeaR VirGln flag — This routine sets SFNVG to Indicate 
the process is not virgin, 

SREADF - Set READF, read access and restricted-access — This 
routine will set the read access bit CREADF) and the 
restricted-access bit (FRKF) In the status word for the selected 
JFN. Also, the previous state of the FRKF flag is returned. 
This routine is required to allow GET to use BIN, SIN, PMAP, etc, 
to a file opened for execute-only access. - 

CREADF - Clear READF — This routine undoes what SREADF did. 



4,1,5,3 Major JSYSs - 

Certain JSYSs have a major role in implementing execute-only. 
These JSYSs are presented below. 



CFORK 

CFORK creates a virgin process if CR%ST (start process) and 
CR%MAP (give process same map as creating process) are not set. 
Note that loading parameters in the ACS using CR%ACS does not 
make this a nonvirgin process. Setting CR%ST and either CR%ACS 
or CR%MAP allows the process to execute code and, therefore, 
mattes the process nonvirgin. Setting CR%ST without CR%MAP or 
CR%ACS seems rather useless. 

CFORK creates an execute-only process if bit CR%map is set and 
the creating process is an execute-only process. This is the 
only way (besides GET) to create an execute-only process, 

SFORK 

SFORK has a switch to indicate that a process is to be continued, 
ignoring any PC change that may be specified in the right half of 
AC2. This is to insure, that an execute-only process is not 
halted and continued "from another location that could cause the 
process to reveal itself. 
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>mS? 

It is illegal to specify an execute-only process as either the 
jource or the destination in a PMAP call unless that execute-only 
srocess is executing the PMAP, If the executing process is doing 
i GET of an execute-only file (that is, if SFGXO is set), the 
jrocess may map pages into any execute-only process, 

JET 

I GET call that addresses an execute-only process is illegal 
inless the calling process is the same execute-only process 

:self), 

Cf the JFN specified in the GET call refers to a file for which 
:he user only has execute access, the process specified must be a 
rirgin process, GET must overcome two protection features to GET 
m execute-only filet 

1, Reading the file without READ access (and not allowing 
others access at the same time), 

2, Mapping pages from the file into an execute-only 
process. 

i GET must then perform the following steps* 

1, Perform OPENF on the file for READ and EXECUTE (as in 
the past), 

2, If the OPENF succeeds, proceed as usual since the file 
is not execute-only, 

3* If the OPENF for READ and EXECUTE fails and either the 
specified process is not virgin or GT%ADR (address 
limits) was specified, return the error from the OPENF, 

4, Perform OPENF for only EXECUTE access, 

5, If Step 4 fails, return the error from the OPENF, 

6, Lock the process structure, 

7, set the execute-only bit (SFEXO) in the destination 
process by calling SETEXO, If the destination process 
is not virgin, the execute-only bit will not be set andi 

a. Unlock the process structure, 

b. Mark the process as not virgin, 

c. Return to step i. Since the process ijs not virgin, 
w step 3 will fail. 
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8, Unlock tne process structure, 

9, Remember that tnis will be an execute-only GET. 

10, Disable interrupts within this process CNOINT). This is 
to protect the use o£ READ access to the file and the 
use of the execute-only GET bit (SFGXQ), 

11, Set READ access and restricted access in the JFN status 
for the selected JFN by calling SREADF. 

12, Set the execute-only GET bit (SFGXO) in the executing 
process by calling SETGXQ, 

13, Perform the normal operations required to GET the file 
into the process, 

14, If any errors occur* clean up but return error. 

15, If this was an execute-only GET, clear the READ access 
and the restricted access in the JFN status by oalU n 9 
CREADF, clear the execute-only GET bit (SFGXO) in the 
executing process by calling CLRGXO, and enable process 
interrupts (OKINT). 

16, Close the file (if possible) using CLOSF. Note that if 
pages are mapped from the file, it will not be closed, 
but will be left open with only EXECUTE access. 



4,1.5,4 Minor JSYSs - 

There are a number of JSYSs that either change a process' context 
or allow access to a process* address space. Since many of these 
functions are disallowed if the process involved is execute-only, 
calls to CHKNXS are contained in these JSYSs, Routines that use 
CHKNXS either directly or indirectly and return the error 
"FRKHX8: Illegal to manipulate an execute-only process" include: 



ADBRK 


AIC 


DIC 


DIR 


EIR 


IIC 


RFACS 


SAVE 


SCVEC 


SDVEC 


SETER 


SEVEC 


SFACS 


SFRKV 


SIR 


SIRCM 


SPACS 


SSAVE 


STIW 


TFORK 


UTFRK 









OPENF returns fail if a attempt is made to open an execute-only 
file with illegal access specified, 

CRJOB creates a virgin process as the top-level process. Thus, 
an execute-only program can be run as the top-level fork, 
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,1.6 BfiSIBICIIDNS &UD LIMIXAXIQAIS 

his section summarizes some restrictions and limitations of the 
urrent implementation of execute^onlys 

1, There is no hardware concealment of process pages. The 
KL10 hardware has the capability to conceal pages within 
a process from other parts of the same process. This 
feature, if used, would provide an additional feature 
that would allow non-execute-only programs to load 
execute-only programs (such as an execute-only object 
time system) into their address space, 

2, There is no protection from a process revealing itself 
through its own carelessness. 

3, Compilers and object time systems cannot be 
execute-only, 

4, There is no page-by-page protection. Only an entire 
file can be execute-only, 

5, Only disk files can be execute-only, 

*m?6t PA1050 roust exist on physical disfc for execute-only 
programs, A user cannot use his own version of PA1050 
with execute-only programs, 

7, An enabled WHEEL cannot create an execute-only process, 

8, The version of an execute-only program cannot be read, 
since that information is stored only in the program's 
address space. 



CHAPTER 5 
MONITOR ADDRESS SPACE 



. 1 MONITOR AODRESS SPACE 

'uring the development of Release 4# the TOPS-20 monitor ran out 

£ address space. Extended addressing could not be used to solve 

he problem. Even though 2060 and ARPA monitors require extended 

ddressing, there are DECS¥ST£M»20s that do not support extended 
d )ssing (2020s and older 2040s and 2050s>, 



.1.1 ADQBES3 S8ACE REABBAMGEMSSX 

o solve the shortage of address space, the symbol table was 
oved out of the monitor address space and placed in an alternate 
ddress space. The symbol table was selected since its removal 
rees a large amount of space and it is used only infrequently 
nder normal conditions. Making the symbol table harder to 
ccess does not degrade normal operations. In addition to the 
emoval of the symbol table, other psects of the monitor have 
een reorganized, 

n order to make the changes easier to understand, the following 
hort description of the address space layout for Release 3A is 
resented. 
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5,1,1.1 ADDRESS SPACE IN RELEASE 3A - 

The address space in Release 3A of TOPS-20 had two layouts (see 
Figure 1) because of two different phases that occured in the 
loading of the monitor. The difference between the two layouts 
was the location of the symbol table. The symbol table was moved 
by POSTLD from its original location to immediately after RSVAR, 
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Before POSTLD After POSTLD 
Notes: 

1. POSTCD 2, PPVAR 3. PPVAR 4, BGPTR 

Figure 1 Release 3A Address space 
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5,1.1,2 ADDRESS SPACE IN RELEASE 4 - 

In order for the symbols to be available from monitor startup 
time, they must reside in the M0NITR.EXE file and be read in by 
BOOT. Any scheme to put them into a different file would mean 
that they would not be available until after all of the monitor's 
disk mounting and other startup code had been executed. This 
would mean that EDDT would have no symbols for debugging. To put 
the symbols into the EXE file without overwriting code or data, 
an all*zero area big enough to hold them must be used. 

Based on this, the monitor's address space is laid out as 

indicated In Figure 2, BOOT reads in RSCOD (resident monitor) 
and INCOD (which contains initialization code and EDDT) and the 

symbols. The symbols are initially read into the area wnere the 

psects PPVAR and RSVAR will ultimately reside. STG then moves 

the symbol table up to immediately following the SYVAR psect In 

physical memory. STG does this to free up the RSVAR and PPVAR 

psects so that mmap and the CSTs can be set up to turn on paging. 

Later, PGRINI sets up SUMMAP to point to an alternate address 
space containing EDDT, the symbols, and parts of the monitor. 
EDDT and the symbols live at the same addresses in this virtual 
address space as they do in physical memory, (See Figure 3.) The 
symbols do not appear in the monitor's main address space at all. 
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NPVAR 



2,3,4 
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NRVAR 
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PSVAR 
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Notes: 

1. PPVAR 2, BGSTR 3. BGPTR 4. POSTCD 
Figure 2 Release 4 Address Space 
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Notes: 

1, PPVAR 2. BGSTR 3. BGPTR 4, POSTCD 
Figure 3 Alternate Address Space 



5,1,2 MODULE CHANGES 

with the changes to implement the alternate address space (which 
is also often referred to as hidden symbol processing) some 
modules now function differently. 



BOOT 

BOOT is read in by the front end at a predetermined physical 
address (currently on top of the RSCOD psect) and started. The 
first thing BOOT does is find the highest 20 pages in section 
of physical memory, and move itself there. It then sets up a 
mapping that is straight physical to virtual, except that it 
always maps itself at the end of virtual memory (pages 760000 and 
beyond). 
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fith Release 4 EDDT now has two conditions. In the first 
condition, when the monitor is loaded by BOOT but not started, 
;he symbols are in the monitor's virtual address space and EDDT 
iccesses them much as it did in past releases. In the second 
condition, the monitor has been started and EDDT must reference 
he symbols using the alternate mapping, 

'he alternate mapping is accomplished using an alternate page 
able. To access the symbols, EDDT changes the page table 
winters at MSECTB and MSECTB+i (for sections and 1), The old 
age table pointers are placed in OSECTB and OSECTB+1, New page 
able pointers are retrieved from SSECTB and SSECTB+i. 

DDT 

DDT accesses symbols when it needs them by mapping needed pages 
f the alternate address space, This is accomplished through the 
se of a new monitor subroutine called ,IMOPR (Internal Monitor 
PeRation) , 



NP"P JSYS 

he SNOOP JSYS accesses symbols in the alternate address space by 
sing ,IMOPR In the same fashion as MDDT, 



.1.3 LIS! QE MQUXXQfi ESECI5 

he following is a list of all of the TOPS-20 monitor's psects, 
long with a short description of each. Note that each psect 
hose name ends in VAR is all-zero, and is not filled in until 
he monitor starts running. 

It Page (and 1 on 2020s) — Not really a psect? these 
pages are loaded with LOC statements and are full of 
miscellaneous communication areas, flags, etc, 

2, RSCOD (Resident code) — This psect contains, the code 
and data that can never be swapped out. This psect Is 
hard-wired into the monitor as the first one, and the 
location MONCOR contains the last page number in it, 

3, INCOD (Initialization code) — This psect contains some 
routines used only during monitor initialization 

w- (including the 143$G dialog). It also contains Exec 
DDT. This psect is locked when the monitor is started, 
but gets unlocked at GETSWM unless EDDT is needed. 
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4, PPVAR (Per-proeessor variables) — This psect contains 
nothing. It is used to reserve a few slots in MMAP for 
use in setting up temporary mappings to. memory pages, 
APRSRV uses these map slots to recover from parity 
errors, for example, 

5, RSVAR (Resident variables) — This psect contains the 
monitor's variables that must always remain resident, 
including the EPT, MMAP, and the CSTs, 

6, SYVAR (Symbol variables) — This psect contains 
everything that should appear only in EDDT's alternate 
address space (for example, symbols), and not in the 
monitor's normal address space. The symbols are 
appended to this psect early in the monitor s 
initialization, and then, both the symbols and the psect 
are "hidden," This psect is of zero size if the HIDSYM 
conditional is not set. 

7, P5VAR (PSB variables) — This psect contains the PSB, 

8, JSVAR (JSB variables) -- This psect contains the JSB. 

9, NRVAR (Nonresident variables) « This psect contains 
monitor data locations that can be swapped. 

10, NRCOD (Nonresident code) — This psect contains the 
monitor code that can be swapped, including the 
processing routines for all the JSYSs. This psect is 
usually write-locked. 

11, BGSTR (Bugstrings) — This psect contains ASCIZ strings 
that describe each BUGINF, BUGCHK and BUGHLT. Like 
NRCOD, this psect is swappable and write-loclced, 

12, BGPTR (Bugpoirtters) — This psect contains a few words 
for each BUGxxx, including the additional arguments and 
pointer to th* corresponding Bugstring. This psect is 
also swappable and wrlte-locked, 

.13, NPVAR (Nonresident page variables) — This psect 
contains monitor variables that are allocated a page at 
a time and can be swapped. One of the main features of 
this psect is the resident free pool (RESFRP), whose 
pages are locked in memory one at a time as they are 
allocated. 
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5.1"f4 HIMIS OH MQUXXQfi BUILDIMfi 

Fhe following hints appear below as an aid to those who must 
rebuild monitors, 

(HY THE PSECTS ARE WHERE THEY ARE 

Several rules must be followed when rearranging the psectss 

1, BOOT reads the monitor in around itself in virtual 
memory. Since BOOT needs to remain mapped and 
functioning until the swappable monitor has been read in 
and started, it must not lie in any part of tne 
monitor's virtual address space that will be used by the 
monitor's initialization code. For this reason, the 
only three areas that can be used are a gap between 
psects, the NRVAR psect, or the last part of the NPVAR 
psect (the first part contains the resident free pool 
that is used by the 
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disk mounting code and the swapper). The last area is 
the one currently used, 

2,' RSCOD must be first; it checks to see if an address 
lies in RSCOD are just CAMLE M0NC0R, which will not work 
if any psect falls below RSCOD, 

3, All of the psects in the part of the monitor that is 
started first and that reads in the swappable monitor 
must be first. In addition, the last item in that part 
of the monitor must be the symbol table, which includes 
the RSCOD, INCOD, PPVAR, RSVAR, and SYVAR psects. The 
code in these psects must work before any swapping or 
paging can occur; therefore, they must all be low 
enough to fit in physical memory on the smallest 
configuration supported. Also, BOOT stops reading in 
the resident monitor when it hits the end of the symbol 
table, so the symbol table must be the last psect In 
this group, 

4, The group of nonzero psects that swap are treated as a 
unit by certain parts of the monitor, and should 
therefore be together. These psects are NRCOD, BGSTR, 
and BGPTR, 

5, PSVAR, JSVAR, POSTCD, NRVAR, and NPVAR can generally be 
put anywhere. They have been moved in the past with 
success. 



5,1.5 WHICH PSECTS CAN OVERLAP 

The POSTCD psect can overlap any xxVAR psect, since It will be 
gone by the time monitr.EXE is generated, POSTCD is currently 
allocated its own three pages to avoid psect overlap warnings 
from LINK (a cosmetic precaution only), 

with hidden symbol processing, the SYVAR psect and the symbol 
table can overlap any other xxVAR psects. The SYVAR psect, is 
currently allocated its own page to avoid psect overlap warning 
messages from LINK, 

If BUGSTF is not set and the bugstrings and bugpointers are not 
present In the running monitor, the BGSTR and BGPTR psects can 
overlap any xxVAR psect. In the current monitor, they would 
probably be overlapped with the NPVAR psect, which Immediately 
follows them. 

No other psect overlaps can be allowed without breaking the 
monitor. 
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5.TT6 HOW TO CONTROL THE SYMBOL TABLE ORIGIN 

The psect origins of all the real psects are controlled by /SET 
switches in the LINK ,CCL file. The symbol table, however, must 
be controlled In a more Indirect way, via the LINK switches 
/SYMSEG and /UPTO, 

The /SYMS£G:PSECT:name switch directs LINK to append the symbol 
table to the named psect. If symbols are hidden, the symbols 
should be appended to INCOD; if not, they should be appended to 
5YVAR, The symbols normally start 200 words after the end of the 
Drecedlng psect. The extra 200 words are the PAT,, area. 

Che /UPTOtaddress switch tells LINK the highest legal address for 
:he symbol table, if there are enough symbols to make the symbol 
:able attempt to exceed the specified address, LINK will output a 
»arning message and truncate the symbol table. (The resulting 
nonitor should still run if this occurs.) The address should be 
jet to one less than the base of the first psect that the symbol 
:able cannot overlap. 
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5,1.7 SAMPLE OUTPUT FROM LINKING A MONITOR 

The following is part of the output from linking a 2020 monitor; 
it shows both a new format for the output and the new address 
layout o 

Monitor address space; 



Psect 


Start 


End 


Length 


Free 


Limit 


RSCCI) 


2000 


63633 


61634 


6144 




INCOD 


72000 


112634 


20635 


1143 




PPVAR 


114000 


117777 


4000 







RSVAR 


120000 


214226 


74227 


13551 




SYVAR 


230000 


230777 


1000 


7000 




PSVAR 


240000 


325777 


66000 


2000 




JSVAR 


330000 


417777 


70000 







NRVAR 


420000 


441426 


21427 


2351 




NRCOD 


444000 


660347 


214350 


13430 




BGSTR 


674000 


702602 


6603 


1175 




BGPTR 


704000 


704714 


715 


1063 




POSTCD 


706000 


710217 


2220 


560 




NPVAR 


711000 


772777 


62000 


5000 


77777 


Loaded symbols 


112735 


251750 


137014 


172027 


NRCOD 


Runtime symbols 


231000 


370013 


137014 


320764 


NPVAR 



The symbols will be moved to their runtime area right after 
the SYVAR psect by STG early in the monitor's initialization. 

There are 57 (octal) free pages, not counting symbols. 

% Runtime symbols must end by 360000 in order to run on a 
128K system. 

Writing sorted bug list to file BUGSTRINGS.TXT. 1 
Saving monitor as SMONITR.EXE. 1 



CHAPTER 6 
MONITOR MODULES 



IQUXXQB MODULES 

he source code for the TOPS-20 monitor is in the form of macro 
lies. Each file contains code pertaining to a particular 
unction or device. These files are assembled into monitor 
odules. some of the modules are assembled from only one file, 
hi'-h may include searching certain universal files. But some of 
h<^modules are a combination of files. For example, consider 
he module TTYSRV. The file TTYSRV, MAC contains the terminal 
ervice functions. The module TTYSRV, however, is built of four 
iles: TTYSRV, MAC, KLPRE.MAC which indicates the terminal 
ervice is for a KL, TTFEDV,MAC which contains information about 
he lines being connected to a front-end, and TTPTDV.MAC which 
ontains the code required to support pseudo terminals, 

11 modules are not contained in every tops-20 monitor. Some 
odules are built for certain hardware and/or software. For 
xample, the TTYSRV module described above is contained in a 
onitor built for a KL10, but the TTYSSM module contains the 
erminai information needed for a monitor that is to run on a 
020, 

he following describes the modules contained in the Release 4 
onitor, 

EfiSBU This is the processor dependent service module for the 
KL10, it contains the initialization code for paging, muuo 
handlers, and the priority interrupt system as well as for 
the clocks, APR, and DTE devices. Interrupt handling for 
these devices, pager control routines, and pre and post JSYS 
handling is also performed here, 

U This is the processor dependent service module for the 
KS10. it performs the same functions as APRSRV Cexcluding 
service for devices that do not exist on the KSiO such as 
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DTE service), 

CDBSBX Card punch service. 

CDBSM Card reader service for the K310 processor, 

CQBSBX Card reader service for the KL10 processor. 

CQHUD Code for the COMND JSYS. 

QAXXME Code for the date and time conversion JSYSs. 

DEXICE Device initialization and lookup code. 

QIAG This module contains the code to support the DIAG JSYS for 
the KL10, 

QXBECX Directory management code, 

DISC This module contains the pre-PHYSIO disk dependent routines 
for I/O JSYSs and a dispatch table of vectored addresses, 
DSKDTB, which points to them, 

QSKALC Drive type independent code for disk block allocation, 
including swapping space allocation, front-end file system 
definition, and structure definition, 

QXEStt Dummy replacement code for DTESRV for the KS10, 

DXESBU DTE service driver; protocol handler for requests to and 
from the front-end, 

EEILIll This module performs the same functions as FILINI using 
extended directory support, 

ENO This module implements the ENQ/DEQ facility to control 
simultaneous access to user specified sharable resources, 

EESBlt Device code for FE devices. This code contains th* 
device-dependent routines for the FE pseudo devices FE0-FE3, 

EILXUX This module contains code to Initialize the file system 
at s-ystem startup, 

EXLMSG This module contains miscellaneous routines for the- PTY, 
TTY string (includes break mask and field width support) and 
null I/O devices and also includes a device dispatch table 
for each of these devices. 

EXLBSB This module contains the filesystem interface to NSP, It 
includes the device dispatch tables for SRV: and DCNS. 

EQBK Contains the fork controlling JSYSs and support code. 
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EEW Job storage free area management, 

EUXXLX Utility module which contains routines to copy strings 
to/from JSBs, routines to retrieve/change connected 
structure and directory information and routines to get a 
yes/no answer from CTY. 

-2JEU Contains the code for GTJFN, and the JSYSs which support 
lookup, recognition, and creation of file names. 

CMAU22 AN22 driver for the 2020, 

LMEAUX IMP driver for AN10. 

CMEDX This module contains the Interface-Message-Protocol (IMP) 
device independent code. It runs cyclically as a separate 
forJc (i.e., under JOB0) and handles the interface to the 
ARPA network by monitoring network activity and managing the 
message queues, 

LMSfiAS This is the parameter file for the IMP modules, 

;0 Contains most of the device-independent sequential, 
random, and dump input/output routines for BIN, BOUT, SIN, 
SOUT, DUMPI, and DUMPO, 

;ECe Code for the system interprocess communications facility, 

ISXSA Random JSYSs for system and directory access, device 
allocation, job parameter settings, system accounting and 
file/fork mapping, 

ISXSE Contains code which implements various file system JSYSs, 

;&SSBX This module provides support for DUPli's with a KMC11 for 
NSPSRV on a 2020, 

iQXttXX This module at load time defines storage PCs for the JSYS 
dispatch table, JSTA8. 

iXUEBfi Lineprinter service for the KLiO, 

XUESli Lineprinter service for the KS10, 

QGUAM Contains the logical name definition and recognition 
JSYSs and routines, 

QQ&UE Device independent file name lookup, 

AGIAE This module contains the pre-PHYSIO magtape-dependent 
routines for I/O JSYSs and a dispatch table of vectored 
^w addresses, MTADTB, which points to them, 

EXEC This module contains the MINI-EXEC (MX) which is a limited 
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command interpreter for certain system loading/maintenence 
functions* and swappabie monitor bootstrap procedures, ^It 
is part of the swappabie monitor and also contains many JSYS 
routines. 

MEILtt Floating point input and conversion JSYSs. 
MSJUQUS Floating point output and conversion JSYSs. 

MSXS Contains the code to implement the mountable structure 
JSYS, MSTR. 

UEiaas This module contains the interface for all standard I/O 
JSYSs that communicate with the ARPA-network, xt ; «i f 2 
provides a finite state machine of various events associated 
with a connection for the network control program (NSP), 

NSB1SX Network Services Protocol Internal interface, 

nsbeAS This parameter module contains data structures and symbol 
definitions required by NSP5RV. In particular, NSPPAR 
contains the definitions of the logical link blocks. 

NSBSBX This module contains the control routines and JSYS 
interfaces for themessage level protocol of DECNET known as 
NSP (Network Services Protocol), which allows communication 
between processes on hosts by means of logical links, 

EASE* Page management coder core management routines, swapper 
routines, pager trap logic, OFN control, and CST and SPT 
initialization. 

eUXUll Channel dependent code for RHil controller. 

EHXH2 Channel dependent code for RH20 controller at direct I/O 
level, 

EHXM2 Device dependent code for TM02/TM45 magtapes at direct I/O 
level. 

EBXfia Device dependent code for RP04/RP06 disks at direct I/O 
level. 

EBXEAB Universal file for PHYSIO and associated modules. It 
contains the definitions for the Channel Data Block, Channel 
Dispatch Table, unit Data Block, Unit Dispatch TAble, and 
the Input/Output Request Block, 

BBXSIQ This module handles the channel and driver I/O routines. 
It is responsible for queueing I/O requests into their 
proper queue, choosing the "best" request for seeking and/or 
transferring and starting I/O. 

BBXX2 Device dependent code for DX20, 
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ZhlT' Plotter service, 

2QSILD This code runs immediately following the loading of the 
monitor f and performs functions outside the capabilities of 
LINK, It builds the M0NITR.EXE file, writes a BUG5TR text 
file and deletes itself from core, 

2EQ£L Parameter file indicating KLiO, 

2BQ&S Parameter file indicating KS10. 

2EQLQG This is a file of parameters, storage assignments,, and 
macro definitions. The major regions of the monitor address 
space are defined as well as macros affecting Pi bug 
strings, pseudo-interrupts, and scheduling. All PSB and JSB 
storage defined by the monitor at assembly time is specified 
here. All of the BUGXXX definitions are included in this 
module from the file BUGS, MAC, 

>XE Paper tape punch service, 

!Xfi Paper tape reader service. 



iCHED This module contains the Channel 7 Interrupt routine 

(which performs context switching), the process controller, 

%p*the working set manager, the }ob/fork initialization/dismiss 

routines, and the Program Software Interrupt (PSD analysis 

and resolution routines, 

EBCQQ This module contains the error codes and fields for 
SYSERR, a program which produces hardware performance 
reports for field service personnel, 

IG The bulk of the monitor storage, both resident and 
non-resident, is defined in this module, 

kBACL This is the swapping space allocator which handles a 
device of some number CSWPSEC) of sectors, and some number 
(DRMMXB) of tracks. It has a resident bit table which is 
used to allocate swapping storage. 

itfiEBB Error reporting module for field service (not to be 
con-fused with the SYSERR program used to read the error 
information) , 

ABE This module contains the tape handler and record processor, 

XMEfi This module implements the TIMER JSYS and all of its 
support, 

17 "M This is the terminal service module for a KSiO arpa 
'••'monitor. See TTYSRV. 

IXSBU This is the terminal service module for a KLIO ARPA 
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monitor. See TTYSRV, 

XXXSSU This is the terminal service module for the KLiO, This 
module contains the TTY I/O drivers, special control 
character conversion routines, terminal JSYS routines and 
the interface to the primary and secondary protocols in 
DTESRV, Its device dispatch table is contained in FILMSC, 

XXXSStt This is the terminal service module for the KS10, See 
TTYSRV. 

UEBSXG Version information for the monitor. 



CHAPTER 7 
WATCH 



M MAXCH 

<ATCH is a TOPS-20 data collection tool that can be used to 
jather the information necessary to analyze both system and job 
>erformance. watch periodically samples many system variables, 
writing them in a format that is usable for analysis. Collecting 
W'H statistics is beneficial whenever the system is running. 
»uw statistics are often useful when usage trends are being 
analyzed in order to plan system growth. Any user can run WATCH 
ind obtain most of the system information and some of the job 
.nformation. These statistics are normally sufficient for 
letermining overall " system performance and for spotting short* 
tnd long-term usage trends. Expanded system and job information 
s available for users who are running with WHEEL or OPERATOR 
•rivileges enabled. This expanded set of statistics provides the 
iuch more detailed information that is often required to observe 
md tune the workload of an individual application. 



,1.1 OUTPUT 

he WATCH output consists- of nine different display sections! 

1. Heading — This section contains the date, time, number 
of jobs logged in, and the time interval over which the 
data sample was collected, 

2, System Statistics — This section contains system-wide 
statistics that reflect the resource utilization of the 
CPU, disk, and memory. 
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3» Load Averages — Load averages indicate the number of 
runnable processes over specified intervals* This 
section indicates the load average for the system, for 
the interactive and computational queues, and for each 
class (when class scheduling is in use), 

4» Directory Cache — A cache of the most recently used 
directories is Kept by the monitor. This section 
displays statistics that indicate the usefulness of this 
cache* 

5. Normal Per-Job Information — Per-job statistics that 
relate the amount of CPU resource distributed to each 
job are displayed along with statistics concerning class 
utilization (when the class scheduler is in use), 

6. Expanded Per-Job Information -- In addition to the CPU 
information, this display presents many statistics that 
show the states in which the job spent time and how 
large the job is. The display also provides disk and 
swapping information. 

7. system utilization Statistics — The system utilization 
statistics include a summary of the expanded per«job 
section, additional system statistics, and computations 
of several Key variables. 

8. Disk I/O — Disk I/O statistics are displayed on a 
per-drive basis. included In these statistics are the 

•number of seeks, reads, and writes performed by each 
drive, 

9. Tune node Display — This display is a single line that 
contains some of the more revealing system statistics 
and summary statistics from the system utilization 
section. It is a useful "quick and dirty" display for 
users who are monitoring changes in the system load. 

In addition to the above displays, data record output can also be 

requested. This form permits further computer analysis of data 

output from WATCH, Consider the following example of system 
statistics: 
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suWary at 8-0ct-79 10:52:21 

for an interval of 1:59,9 with 54 active jobs. 



USED! 


21.1 


idle: 


42.7 


swpw: 


2.0 


SKED: 


2.9 


5USES 


20,7 


TCOr: 


0.1 


FILW: 


29.6 


BGND: 


1.6 


itrp: 


10,2 


NCORI 


2.00 


AJBL: 


21.03 


NREMj 





rRAPs 


1.2 


nrun: 


0.9 


NBAL8 


0,9 


NWSHj 


66,6 


3SWTS 


0,5 


DSKRJ 


18,0 


DSKW; 


9,4 


SWPRl 


5.7 


aoD: 


13.52 


ctxs: 


21.9 


upgs: 


1966, 


FPGS: 


205. 


JMRDI 


1.1 


DMWRJ 


0.7 


DKRDJ 


3,0 


DKWR: 


2,5 


niN: 


12.8 


TTOUS 


242. 


wake: 


13,7 


TTCC: 


2,50 


rDio: 


7.4 


RP05I 


3.3 


GCCW: 


1.6 


xgcws 





(NOB: 


11 














3UEUE 


DISTRIBUTION P 


ERCENT* 


ige: 









0,20 6.95 10.28 3,64 0,00 0,00 



the output data record for 
following form: 



this WATCH output would have the 



>1001 10/08/79 10:52:2100119,90540021,100042,700002,000002.90 
>020. 700000, 100029, 600001. 6000 10, 200002, 000021, 030000. 000001 
,200000,900000,900066,600000,500018,000009,400005,700013.520 
121.901966,200205,400001,100000,700003,000002,500012,600242. 
'00013,700002,500007,400003,300001,600000,00000110000,200006 
9 P "01 0,280003. 640000, 000000, 000000, 000000, 000000, 000000, 000 



,11 of the variables and the format of the data records 
escribed in the "WATCH VARIABLES" section that follows. 



are 



.1.2 RUNNING WATCH 

ATCH can be run by all users, though users with OPERATOR or 
HEEL privileges enabled can obtain more information than others, 
ATCH is run by typing either "WATCH" or "R WATCH". When WATCH 
tarts, it identifies itself with a message like: 

ATCH 4(3), /H for help, 

nformation is then requested in the following order: 

Output to file: 

Would you like to output data records? C¥/N) 
Output file for data records: 
Print monitor statistics? 
Print Job summary ? 
"une mode? 
^lme period (mm:SS): 

ome of these requests are not made if previous answers indicate 
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The following diagram 



that the information is unnecessary, 
outlines the order of the questions: 

Output to file: 



Would you like to output data records? Cy/n): 

MO I » *ES 

I 

output file for data records: 
I 
I 
Print monitor statistics? 
I I 

ALL I « YES I NO 
I I 

Print job summary? 
I • / \ 
YES I / N NO 
or I /YES \ 
MO | / Tune mode? 

I / / 

I / / YES or NO 

I / / 

Time period (MM:SS): 

The output of data records is indicated with the second and third 
questions. The output display received is as follows: 

Headings and load average displays are always received 
except in tune mode. 



"Yes" to the monitor statistics question causes the 
system statistics display to be output, 

"Yes" to the job summary question causes the normal 
per-job statistics display to be output, 

"All" to the monitor statistics question causes all 
displays but the tune mode display to be output, 

"Yes" to the tune mode question (which occurs only when 
"no" is given for both the monitor and job summary 
questions) causes the tune mode display to be output. 



After the user enters the necessary information, WATCH displays 
the message: 

WATCH IN OPERATION -• 

and then taxes its first sample. This message is seen 
immediately after entering the interval time unless the user is 
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requesting displays that require privileges (extended and tune 
mode). Then, a 10-30 second pause occurs (depending on system 
load) while the snoop breakpoints necessary to collect the 
Information are Inserted into the TOPS-20 monitor, 

when the user desires to stop collecting statistics, the 
following procedure should be followed* 

*C 
*C 

CLOSE 
RESET 

At this point, the output can be printed. 



7,1,3 SOME INDICATORS 

When variables have the values Indicated in the following list, 
the system is usually in "balance," Since it Is quite possible 
Cor one variable to appear in balance, while others are not, this 
Ln'^rmation is only a auideJLioe, 

1, NCOR a 30 PER MINUTE — Expensive If higher, 

2, NRUN/NBAL si— All processes wanting to run can fit in 

memory, 

3, SWPR less than 20% — Swap reads/writes are overhead and 
thus should be (ideally) a small component of disk 
usage, 

4, swpw close to — Since this variable represents 
processes waiting for memory when no others can run, 
utilization of the system can normally be increased by 
adding memory until this Is a small value. However, If 
the load has a large I/O component, additional memory 
may merely shift the CPU Idle time from SWPW to FILM, 

5, sked s 15% — scheduler overhead detracts from cycles 
going to user programs. Programs that do very little 
work each time they are scheduled generally drive this 
value up. If this value is high, It is important to 
determine if there is a set of applications which could 
be reprogrammed in order to do more work between 
interactions. Programs that become active as each 
character is typed (like some screen formatting 
software) should be viewed with suspicion. 
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6, FILW close to — This is CPU idle time caused by 
processes waiting for disk I/O to complete. More memory 
permits larger numbers of programs to be resident. At 
other times, reconfiguring the disk access patterns to 
spread the dislc I/O more evenly across the disks and 
channels lowers this value. 

7„ BSWT/NBAL small — If a large proportion of processes in 
memory are waiting on the disk, the CPU is not being 
utilized, 

8, NREH = — Since this counts the times runnable 
processes are removed from the balance set, performance 
is best when it is zero. Performance degrades rapidly 
as the value increases, 

9, FPGS large — If the number of free pages is low, the 
system needs to expend resources to garbage collect more 
often. This statistic, along with NREM, can be used to 
indicate a system overload. 

10. DMRD+DMWR less than 20 per second — Because drum 
reads/writes utilize a percentage of the disk system s 
bandwidth, higher throughput is possible when swapping 
is low. Normally, swapping of less than 30 pages per 
second does not cause any visible effect. If the normal 
load contains a large amount of user disk I/O, swapping 
at rates higher than 20 will decrease the system 
throughput. If the normal load is mostly interactive or 
computational, higher swapping rates can be sustained. 



7,1.4 WATCH VARIABLES 

The following is a list of the displays produced by WATCH, 
Beside each display type is the output data record type used for 
that display's information when data records are written, 

1, Heading (All record types) 

2, System Statistics (01) 

3, Load Average (02) 

4, Directory cache (05) 

5, Normal Per-Job Information (04) 

6, Expanded Per-Job Information (03) 
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7, System Utilization Statistics (05) 

8, Disk I/O Statistics (05) 

9, Tune Mode statistics (06) 



In the following sections, each display is described and the 
format of the output data records Is given. In the formats of 
:he data records, the length of the fields is measured in 
rharacters (all fields In the records are ASCII characters). The 
!orm of each field Is shown as a COBOL PICTURE (9 represents a 
tumeric character, X an alphanumeric character). The first field 
>f each record is the record type; the second field is the 
"ecord sequence number. For record types 01, 02, and 05, the 
•ecord sequence number is always "001", 



,1,4,1 Heading - 

'he following is an example of the heading display. It shows the 

lar and time, the length of the interval, and the number of 

sBm logged in. The Interval shown is nearly equal to that 

peclfied by the user. 



SUMMARY at 6-Aug-79 09:28:23 
for an interval of 0:11,3 



with 52 active jobs. 



he heading information appears In fields 3, 4, and 5 of all 
utput data records. 



•1,4,2 System Statistics - 

he following example of the system statistics display may 
eferenced while reading the descriptions of the variables, 



be 



USED: 

suse: 

NTRP: 
TRAP: 
BSWT: 
NLOD: 

DMRDS 

rT : 

ro^rtf: 
knob: 

3UEUE 



87.6 
80,0 
22.3 

3,2 

2,8 

16,12 

4,1 

11.0 

23,8 

11 



IDLE: 
TCOR: 

NCOR: 
NRUNs 
DSKR: 

ctxs: 

DMWR: 

ttou: 

RPQSl 



0,0 

0,1 
2,02 

5,7 
23.0 
64,1 

4.7 
401, 

4,4 



swpw: 
filw: 
ajbl: 

NBAL: 
DSKW: 

upgs: 

DKRD; 
WAKE: 
GCCW: 



0.0 

0,8 

53.44 

5,7 

4.8 

1992. 

10.7 

18.3 

6,4 



SKEDn 
BGNDi 
NREMJ 
NWSMS 
SWPRl 
FPGSS 
DKWRi 
TTCCS 

xgcw: 



10,0 

1,8 



61.0 

6,4 

147, 

4,3 

1,51 





DISTRIBUTION PERCENTAGE: 
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0,19 20,48 21,28 11.04 2,69 31,74 

The statistics in this display are expressed either as 
percentages (%), as averages (AV), or as rates (Px). The rates 
are In units per minute CPM) or in units per second (PS), 

The display Includes "CPU usage statistics" from which the 
distribution of the CPU resource can be determined, The usage 
statistics are all percentages? their sum should be 100% _(+/- 
roundoff error). The CPU Usage statistics are USED, IDLE, swpw, 
SKED, TCOR, FILW, BGND, and possibly TRAP, 

Each of the variables in the example are described below? they 
are taken line by line in left-to-right order, 

USED! (%) — Percentage of the interval during which the CPU was 
executing instructions on behalf of some user. This 
includes user, JSYS, page fault, and Interrupt processing* 

IDLE: C%) -- Percentage of the interval during which the CPU was 
idle because there were no active processes on the system. 
If this number is nonzero, the system can accommodate some 
additional usage. If the CPU Is idle when there are active 
processes, its idle time is accounted for in swpw or FILW, 
not under IDLE time, 

swpw: (%) — Percentage of the interval during which the CPU was 
idle and while one or more processes was waiting on the 
completion of a memory management service (normally a swap 
in). For time to be accounted in this variable, all active 
processes must be In wait states, 

SKED: (%) — Percentage of the interval during which the system 

was scheduling users for memory and the CPU, other system 

overhead functions are measured by tne variables TCOR and 
BGND, 

SUSE: (%) — Sum of the runtime percentages accumulated for each 
job running at the time of the report. This value differs 
from USED only by the skew that builds up during the time 
that it takes WATCH to collect all of the data about each 
job and by the loss of data from jobs that logged out during 
the interval, 

TCOR: (%) — Percentage of the interval spent garbage collecting 
memory. This represents part of the memory management 
overhead. The garbage collection process requires the 
monitor to look at the age of each page In memory to 
determine the ones that have not been referenced In a while. 
The least recently used pages become the prime candidates 
for being swapped out. 

FILW: (%) « Percentage of the interval during which the CPU was 
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idle, no processes were waiting for memory management 
services, and at least one active process was waiting for a 
short-term, user-initiated event (disk I/O) to complete, 

3GNDt (%) — Percentage of the interval during which the monitor 
was performing background tasks. The primary background 
task is moving terminal input characters from a system-wide 
buffer to the individual terminal input buffers. This 
variable also includes the CPU overhead to echo terminal 
input characters, 

*TRPs (PS) — Number of page fault traps per second. Not all 
page faults require disk input to be resolved. Some page 
faults are resolved with pages that are currently in memory 
but not assigned to the process generating the page fault. 
Some of these pages are found in the replaceable queue (see 
RPQS below) while others may be shared by other processes, 

ICOR: (PM) -- The average number of memory garbage collections 
per minute performed by the monitor during the last 
interval, 

»JBL: (PM) — The average number of times per minute the system 
was forced to adjust the balance set during the last 
interval. A rate of 60 times per minute is normal on a 
w system with several users and no IDLE time, 

irem: (PM) -- The average number of times per minute the monitor 
had to remove a process from the balance set before the 
process came to a natural wait state (such as terminal input 
wait). This number becomes nonzero whenever there are more 
jobs to be run than can fit simultaneously in memory, 
whenever this situation occurs, the monitor removes 
processes from the balance set, swapping them out to make 
room for other runnable processes. In general, whenever 
this number goes nonzero, response time gets .longer, 

RAPs (%) — Percentage of the interval during which the CPU was 
responding to page faults. This time is normally charged to 
the user, and is therefore also part of "USED" time. If the 
monitor was built to remove this "TRAP" time from "USED" 
time, it will become part of the system overhead (like SKED) 
and cannot be billed. In such a case, the TRAP time must be 
added to the "CPU Usage Statistics" in order to account for 
100% of the CPU time, 

RUN: (AV) mm xhe average number of processes that were 
simultaneously active during the interval. This number 
represents the CPU load on the system during the interval. 
When NRUN is greater than 1,0, the user programs experience 
an average execution time at least "NRUN" times longer than 
^■^ifi the system were stand-alone. 

BALs (AV) « The average number of processes in the balance set 
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during the interval. If this number is less than NRUN by 
more than ,5, the implication is usually that there is not 
enough memory to hold all active processes, 

NWSM: (AV) •- The average number of working sets in memory 
during the interval. If this number is significantly larger 
than nrun or NBAL, working sets are not being forced out of 
memory when processes go into a wait state (like terminal 
input wait) and, consequently, response times should not be 
greatly affected by paging, 

BSWT: (AV) «•• The average number of processes in the balance set 
that are waiting for the completion of some event, Normally 
this number reflects the number of processes waiting for a 
page to be read in from the disk. If NBAL - BSWT is less 
than one, there are not enough runnable processes in memory 
to keep the CPU busy 100% of the time. The idle time is 
included in SWPW or FILW, 

DSKR: (%) — Percentage of the processes in balance set wait 
(BSWT) that are waiting for a file page to be read into 
memory, 

DSKWs (%) — Percentage of the processes in balance set wait 
(BSWT) that are waiting for file pages to be written back to 
the disk, 

SWPR: (%) — Percentage of the processes in balance set wait 
(BSWT) that are waiting for a page to be swapped into memory 
from the swapping area of the disk, 

NLOD: (PM) — The average number of working sets loaded per 
minute into memory, 

CTXSi (PS) •- The average number of context switches performed 
per second by the scheduler, A context switch happens when 
the running process voluntarily blocks, or faults on a page 
that is not in memory, or when a higher priority process Is 
ready to run. Since it takes CPU time to perform a context 
switch, CTXS directly affects 5KED, 

UPGs: (AV) « The average number of pages assigned to processes 
with loaded working sets. These processes may or may not be 
in the balance set, but they are allocated memory. 

FPGS: (AV) — The average number of physical memory pages that 
are currently available for swapping in user processes. The 
monitor normally keeps between 20 and 100 free pages. The 
monitor uses these pages (and the rest of memory not in use 
by balance set processes) as a page cache. For example, if 
a process reenters the balance set after waking up from a 
blocked state and it still has some of its pages in memory 
in the free page pool, those pages are used directly without 
requiring any disk I/O, It has been demonstrated that this 
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cache plays an Important part in overall system performance. 
Therefore, if FPGS is very small, the system performance has 
most likely been degraded, 

>MRD» CPS) — The number of reads per second made to the 
swapping area, 

>mkr: CPS) -- The number of writes per second made to the 
swapping area, 

>KRDr CPS) — The number of reads per second made to the file 
system, 

ikwr: CPS) — » The number of writes per second made to the file 
system, 

'TIN: CPS) — The number of terminal input characters received 
per second from all terminals Creal and pseudo) on the 

system, 

TOU: CPS) — The number of terminal characters output per 
second by all jobs on the system. This includes real and 
pseudo-terminals, 

AK"** CPS) — The number of process wake-ups per second. Some 
ij^of the types of wake-ups that fall into this category are 

IPCF Process Termination 

ENQ DISMS 

Terminal Input TIMER 

Terminal Output IIC 

TCC: CPS) — The number of terminal interrupt characters Ce.g., 
CTRL/C) typed per second, 

DIOs CPS) -- The aggregate number of disk pages read or written 
per second to both the file system area and the swapping 
area. Normally, 60 pages per second for a one-channel and 
100 pages per second for a two-channel system are saturation 
levels. This variable is the summation of DMRD, DMWR, DKRO 
and DKWR, 

PQS: CPS) — The average number of pages per second that were 
retrieved from the replaceable queue in order to satisfy 
page faults. These page faults do not require disk I/O, 

CCWt CPS) — The average number of pages per second that were 
freed by global garbage collections, 

SCWs CPS) — The average number of pages per second that were 
freed by local garbage collections on specific processes, 
'These garbage collections remove tnose pages from a process* 
working set that have not been used in a long time. 
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KNOB: (value) — This is the setting of the bias control Knob, 
The twenty possible bias control knob settings can only 
represent six switch settings in Release 4, Low settings 
favor interactive jobs; high settings favor compute-bound 
jobs. The default setting is 11, 

The QUEUE DISTRIBUTION PERCENTAGE represents the portion of USED 
tine allocated to processes in the various scheduling gueues. 
The first gueue is only used by Job and Jobs in the special 
high priority category. Normally the percentage of runtime 
accumulated in this gueue is small. The second and third queues 
are the interactive gueues. If the sum of these two values is 
high, there is a high interactive load on the system. The last 
three gueues are the computational queues. Processes move onto 
these queues only if they have entered a compute-bound phase. If 
the sum of these three values is high, the system load is 
primarily computational. When the class scheduler is turned on, 
interactive users are scheduled in queue order while processes in 
the lower three (computational) queues are given priority on the 
basis of their class' distance from its target share. 

The system statistics data record (record type 01) has the 
following form: 

Item Length Picture 

1, Record Type 2 99 

2, Record Sequence Number 3 999 

3, Date & Time 17 X(17) 

(MM/DD/YY HH:MM:SS) 

4, Interval 7 9(5). 9 

5, Number of Jobs 3 999 

6, USED 7 9(4). 99 

7, IDLE 7 9(4),99 

8, SWPW 7 9(4), 99 

9, SKED 7 9(4),99 

10. SUSE 7 9(4). 99 

11. TCOR 7 9(4),99 

12. FILW 7 9(4). 99 

13. BGND 7 9(4>,99 

14. NTRP 7 9(4). 99 

15. NCOR 7 9(4).99 

16. AJBL 7 9(4). 99 

17. NREH 7 9(4).99 

18. TRAP 7 9(4>.99 

19. NRUN 7 9(4). 99 

20. NBAL 7 9(4>,99 

21. NWSM 7 9(4). 99 

22. BSWT 7 9(4). 99 

23. DSKR 7 9(4).99 

24. DSKW 7 9(4), 99 

25. SWPR 7 9(4). 99 

26. NLOD 7 9(4).99 

27. CTXS 7 9(4). 99 
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!8l?»0PGS 7 9 (4). 99 

!9, FPGS 7 9(4). 99 

10, DMRP 7 9(4),99 

U. DMWR 7 9(4), 99 

12, DKRD 7 9(4),99 

•3, DKWR 7 9(4).99 

14, TTIN 7 9(4), 99 

15, TTOU 7 9(4),99 

16, WAKE 7 9(4). 99 

7, TTCC 7 9(4), 99 

8, TDIO 7 9(4), 99 

9, RPQS 7 9(4), 99 
0. GCCW 7 9(4).99 
It XGCW 7 9(4),99 

2, KNOB 5 9(5) 

3, Queue Distribution %'s 70 

Max 10 entries; each entry 9(4), 99 

4, Number of Queue Dist Entries 2 99 

Total 361 Characters 



» L^ ..,3 Load Averages - 

he term "Load Average" refers to the average number of processes 
imultaneously demanding service over some interval of time. The 
ollowlng is an example of the load average display; 

LOAD AVERAGES: 

HIGH QUEUE AVERAGES: 

LOW QUEUE AVERAGES: 

CLASS LOAD AVERAGES 
CLA SHR UTIL 



5,29 


"4,06 


3.39 


3,76 


2.86 


2,25 


1.54 


1,20 


1,14 






80,00 


96,20 


4.70 


3,08 


2,94 


1 


15,00 


3.80 


0.23 


0.19 


0.15 


2 


5,00 


0,00 


0.00 


0.00 


0,00 



DAD AVERAGES— The system keeps three exponential load averages, 
iese values represent the average load over the last 1 minute, 
ie last 5 minutes, and the last 15 minutes. These numbers can 
i used to estimate the expected elongation of the elapsed time 
jquired to run a program. If the system load average equals X, 
ie approximate elapsed time required to run an additional 
:on"am on the system is at least (1+X)*Y, where ¥ is the 
la^^-alone elapsed time required to run this program. 
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HIGH QUEUE AVERAGES— These values represent the load of 
Interactive jobs (queues 1 and 2), 

LOW QUEUE AVERAGES— These values represent the load ,of 
compute-bound jobs (queues 3, 4, and 5). The sum of the high 
queue average and the low queue average equals the load average, 

CLASS LOAD AVERAGES— This display is of interest when class 
scheduling is being utilized. The following information is 
presented for all classes defined for the system, 

CLA — The class number, 

SHR — The class share of the processor. This share corresponds 
to the percentage of the CPU that the monitor will try to 
distribute among the jobs in this class, 

UTIL — The actual utilization achieved by each class. The value 
here should be less than the share unless the class has 
received some windfall. 

The 1-minute, 5-mlnute, and 15-minute load averages are displayed 
for each of the classes. These load averages may appear to be 
very large because they are computed as follows: 

* processes in class making demands 
Class Load Average = .-—————— —————— -—----— 

Maximum (Share, utilization) 

Thus, if there are 5 processes making demands in a class with a 
share of .20 and a utilization of .15, that class' load average 
is 25 (5/, 20). 

If the class scheduler is not running, the utilization and load 
averages are all zero. 

The following is the form of the load averages data record 
(record type 02): 

Item Length Picture 

1, Record Type 2 99 

2, Record Sequence Number 3 999 

3, Date & Time 17 X(17) 

(MM/DD/YY hh:mm:ss) 

4, Interval 7 J' 5 , 5,9 

5, Number of Jobs 3 999 

6, Load Averages (3 values) 21 

Each Value 9C4),99 

7, High Queue Avgs (3 values) 21 

Each Value 9(4). 99 
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Sw&ow Queue Avgs (3 values) 21 

Each Value 9(43,99 

9, Class Load Averages 

Max 32 entries! 
each entry as follows* 

a. Class Number 5 9(5) 

b. Share 7 9(4). 99 

c. Utilization 7 9(4). 99 

d. Load Avgs (3 values) 21 

Each Value 9(4), 99 

lO, Number of Class Load Avg, 2 99 

mmmm 

Total 1377 Characters 



',1,4,4 Directory Cache statistics • 

:he directory cache statistics are only available when an enabled 
iser responds "ALL" to the question "Print monitor statistics ?", 
'he following is a sample display: 

Directory Cache hits; 175 
directory Cache Misses - Cache Full* 
directory Cache Misses - New Entry Added: 321 

irectory Cache hits: — The number of times an accessed 
directory was found in the cache, 

irectory Cache Misses - Cache Full: — The number of times an 
accessed directory was not found in the cache while all the 
cache slots were filled with active directories. In this 
case the most recently accessed directory cannot be put into 
the cache, 

irectory Cache Misses - New Entry Added: « The number of times 
the accessed directory was not found in the cache, though 
room was available to add it (possibly as a replacement for 
an inactive entry), 

he "hit ratio" is computed by HITS/(HITS+MISSES) and provides a 
ood indication of the cache's effectiveness. For instance, the 
it ratio in the example is 175/(0+321) or 35% (not very good), 

he directory cache portion of data record type 05 is shown in 
he "Disk I/O Statistics" section below. 
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7.1,4,5 Normal Per-job Information - 

The normal per-job information which is available to all users 
running WATCH and consists of a line for each job that had an 
active process during the interval. The following example shows 
the statistics reported for each jobt 

JOB TTY USER PROGRAM DELTA RT %RT JU CSH 






OET 


OPERATOR 


SYSJOB 


7,81 


4.3 


23.94 


3.64 


1 


43 


OPERATOR 


PTYCON 


1.71 


0.9 


1.86 


3.64 


5 


47 


OPERATOR 


OPR 


0,35 


0.2 


0.28 


3.64 


10 


3 


KELLEY 


BASIC 


5,31 


3.0 


9,85 


3.64 


13 


12 


DENNING 


EXEC 


8,46 


4,7 


7.17 


3.64 


14 


24 


KOVALCIN 


WATCH 


3.80 


2.1 


3.92 


10.00 


16 


2 


GRAVES 


BASIC 


3.72 


2.1 


9.18 


3.64 


18 


21 


BLIZARD 


SYSTAT 


4.46 


2.5 


13.55 


3,64 


19 


14 


BOYACK 


EDIT 


10,74 


6.0 


20.71 


3.64 


20 


20 


WOLFE 


EDIT 


0,27 


0.1 


0.34 


3.64 



JOB — The job number assigned by the system when the user logged 
in. 

TTY — The number of the terminal that is being used by the user 
running this job, »DET" means detached. 



USER 



« The name of the directory that the user logged into. 



PROGRAM — The name of the program being run or the name of the 
EXEC command being used. Please note that the program name 
is obtained at the time the sample is taken. It is not 
possible to tell if the program or command was running 
during the entire interval. 

DELTA RT «■- The incremental amount of CPU time (in seconds) that 
the job used during the interval, 

%RT — The percentage of the interval represented by the DELTA 
RT. The sum of all %RT values is used to compute the SUSE. 

JU — Job Utilization, When the class scheduler is running this 
will normally be a nonzero value. It represents the CPU 
utilization accumulated by this job and charged to the job's 
class share. Because the class scheduler tries to divide 
the class share equally among all active users In the class, 
computational jobs within the same class should normally 
receive nearly the same job utilization, 

CSH — Class Share, When the class scheduler is running, this 
value reflects the class* share divided by the number of 
active jobs in that class — this is the target share for 
the job. Normally the job utilization (JU) is less than a 
job's class share. 
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fh^^ Is one normal per-job data record Crecord type 04) for each 
Job. The sequence numbers begin with "001" and increment by 
•001", The form of a record Is 

Item Length Picture 

1» Record Type 2 99 



2. 


Record Sequence 


Number 


3 


999 


3. 


Date & Time 

cmm/dd/yy m 


iimmsSS) 


17 


XU7) 


4. 


Interval 




7 


9(5), 9 


5. 


Number of Jobs 




3 


999 


6. 


Job Number 




3 


999 


7. 


TTY Number (777 


= DET) 


3 


999 


8, 


User Name 




20 


X(20) 


9. 


Program Name 




6 


X(6) 


0. 


DELTA RT 




7 


9(4), 99 


1. 


%RT 




4 


99.9 


2. 


JU 




7 


9(4),99 


3. 


C5H 




7 


9(4).99 



Total 89 Characters 



,1,4,6 Expanded Per-job Information - 

ost of the Information presented in this display is obtained by 
ettlng breakpoints In the monitor with the SNOOP JSYS, Thus, 
his information is only available to users who are running WATCH 
ith either WHEEL or OPERATOR privileges enabled, 

he presented information occupies a fun 132-character line, 
or purposes of explanation, the columns are broken up as 
oiiows: 

ob Identification informations 
08 TTY USER PROGRAM 

hese variables are the same as those listed in the normal 
er-job display, 

ob Utilization Information: 

RT DEMD USED GRDY BRDY SWPTR DSKR DSKW RPQW OTHR 

emory, Response, and Disk informations 

HF NLD NRSP RESP SP WSS UPGS SWPR DSKR TPF IFA 

r>e job utilization information and memory, response, and disk 
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information are discussed In the next two sections below. 



JOB UTILIZATION INFORMATION 

The following is an example of the job utilization portion of the 
extended per-job display: 

JOB .... %RT DEMD USED GRDY BRDY 5WPR DSKR DSKW RPQW OTHR 





2 

4 

7 

9 

10 

12 

15 

16 

19 



1.0 


14.3 


8,6 


0.1 


0.7 


18.0 


0.6 


3.6 


19.3 


0.0 


0,3 


15.5 


0.5 


1.2 


43.0 


9.7 


49.8 


20.7 


0.1 


0.4 


29.4 


1.0 


6,0 


19.4 


22.4 


38.7 


61.5 


1.1 


5.7 


27.7 



72.9 5.7 
82.0 

34.8 38.4 
19.3 65.2 



4.0 

5.8 



15.7 
63.5 
70.6 
20.2 
38.5 
72.3 



35.6 
2.9 11.9 



8.8 

1.8 

5.7 
0.9 



0,5 



1,1 16.0 43,3 



%RT (%) « The percentage of the interval during which this job 
actually received CPU time,, 

DEMD C%) — Summation of the percentages of the interval that 
each process in the job was active. If only one process In 
the job is active during the interval (the normal case), 
DEMD Is less than or equal to 100%, If more than one 
process are simultaneously active, DEMD could exceed 100% 
(for a job of n processes, DEMD could be up to n*100%). 

The rest of the variables in this display indicate what a job was 
doing during its "active" period, These statistics are all 
expressed as percentages of DEMD and thus their sum is 100%. 
When assessing the importance of the statistics for a specific 
job, you should multiply these percentages by DEMD to get the 
percentage of the interval time, 

USED (%) — The percentage of DEMD that the processes in this job 
spent using the CPU, 

GRDY (%) — The percentage of DEMD that processes in this job 

were runnabie but could not fit In the balance set. The 

most common cause for processes to be on this list is that 
there is not enough memory to hold all runnabie jobs, 

BRDY (%) — The percentage of DEMD that processes in this job 
were in the balance set but were not being run. Usually 
processes in this state are waiting for their turn to use 
the CPU, 

SWPR (%) -- The percentage of DEMD that processes In this job 
waited for page faults from the swapping area to be 
satisfied. 
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55^ C%) — The percentage of DEMD that processes In this job 
^ waited for file pages to read in from the disk:. 

3SKW (%) « The percentage of DEMD that processes in this job 
waited for file pages to be written to the disk. 

*PQw (%) — The percentage of DEMD that processes in this job 
waited for a physical memory page to become available for 
swapping into, usually, when time is accumulating here, 
there is a shortage of memory on the system, 

JTHR (%) — The percentage of DEMD that processes in this job 
spent in any of the other wait states. 



'.1.4,7 Memory, Response, And Disk Information - 

'he following is an example of the memory, response, and disk 
.nformation portion of an extended per-job displays 

JOB,,,,IMEM NLD NRSP RESP SR WSS UPGS SWPR DSKR TPF IFA 






917,1 


1 


165 


0,06 


6 


410,0 


7,7 


20 


17 


45 


40 


1^, 


99,9 





12 


0,07 


6 


8,0 


7.0 












192.5 


3 


28 


0,11 


6 


37.0 


7.2 


29 


4 


57 


25 


7 


78.2 





1 


0,39 


6 


27.0 


25,0 


8 





32 


7 


9 


99,9 





12 


0,12 


2 


56,0 


54,8 





9 


57 


69 


10 


198,1 


4 


95 


0,12 


5 


124,0 


54,2 


32 


109 


62 


87 


12 


199,8 





17 


0,03 


3 


18,0 


7,6 












15 


99,9 





12 


0.61 


5 


27,0 


17,2 


3 


24 


45 


51 


16 


99,9 





357 


0,13 


2 


22,0 


20,6 












19 


99,9 





329 


0,02 


4 


15,0 


13,1 













MEM C%) — The percentage of the time that the working sets of a 
job's processes are in memory. This number is the summation 
of the percentages for each process in the job and thus may 
exceed 100%, 

ID CCNT) — The number of times working sets for processes in 
this job were loaded into memory. If this number is zero, 
no working sets .were loaded during the interval Ci.e,, the 
working sets were in memory for the whole interval), 

RSP CCNT) — • The number of responses that a job had during the 
interval, A response is counted whenever a process wakes up 
for one of the reasons specified under WAKE*. 

ESP (AV) « The average response time in seconds during the 
interval. Responses that require more than two seconds of 
n^CPU time to finish are not counted in this column. 
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SR O — The "stretch ratio" for each response (as represented in 
RESP). The stretch ratio is obtained by dividing the 
elapsed time of each response by the compute ^time required 
to satisfy it. (SR = elapsed time/CPU time). The only 
responses counted are 1 those that require less than two 
seconds of CPU time to complete. Thus, the stretch ratio is 
the elongation perceived by the interactive user, 

WSS (SUM) « The sum of the maximum working set sizes of all 
active processes in the job. 

UPGS (AV) — The average number of pages actually in memory when 
a process from a job is in the balance set, 

SWPR (CNT) — The number of times a process in a job waited for a 

faulted page to be read in from the swapping area. This 

does not include pages that were preloaded by the working 
set manager. 

DSKR (CNT) — The number of times a process waited for a disk 
read to complete. Because many programs prefault pages, 
this count will be different from the actual number of pages 
read. 

TPF (AV) -- The average number of milliseconds that it took to 
satisfy each page fault for this job during the interval, 

IFA (AV) « The "inter-fault average". This value represents the 
averaae compute time in milliseconds between page. faults for 
job, A large "TFA" means that the working sets of processes 
in this job are very stable. 

There is one expanded per-job data record (record type 03) for 
each job. The sequence numbers begin with "001" and increment by 
"001", The form of the record is 

Item Length Picture 

1, Record Type 

2, Record Sequence Number 

3, Date & Time 

(HM/DD/YY HHSMMtSS) 

4, Interval 

5, Number of Jobs 

6, Job Number 

7, TTY Number 

8, User Name 

9, Program Name 

10. %RT 

11. DEMD 

12. USED 

13. GRDY 

14. BRDY 

15. SWPR • 



2 


99 


3 


999 


17 


X(17) 


7 


9(5). 9 


3 


999 


3 


9(3) 


3 


9(3) 


20 


XC20) 


6 


X(6) 


4 


99,9 


6 


9(4). 9 


5 


999,9 


5 


999.9 


5 


999,9 


5 


999,9 
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•6»JSKR 
.77"DSKW 

,8. RPQW 

,9. OTHR 

10, IMEM 

!1. NLD 

!2. NRSP 

13, RESP 

!4» SR 

!5, WSS 

6, UPG5 

7, SWPR 

8, DSKR 

9, TPF 
0. IFA 
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5 


999.9 




S 


999,9 




5 


999.9 




5 


999.9 




6 


9(4),9 




4 


9C4) 




5 


9(5) 




6 


999.99 




3 


999 




7 


9(5),9 




7 


9(5). 9 




5 


9(5) 




5 


9(5) 




4 


9999 




4 


9999 





Total 170 Characters 



.1.4.8 system Utilization Statistics - 

wo sections comprise the system utilization statistics, The 
ir*t consists of summaries for expanded per-job statistics, 
nt^ding summaries for the job utilization information and the 
emory, response and disk information. The second consists of 
dditionai system variables and several computations. 



,1.4.9 system Summary Of Per-job Variables - 

hese statistics are listed under the per-job statistics on the 
lne that begins "System summary". The following Is an example 
t such a summary: 

DEMD USED GRDY BRDY SWPR DSKR DSKW RPQW OTHR 
539,2 28,6 51.9 5,0 11,5 3,0 



IMEM NLD NRSP RESP SR WSS UPGS SWPR DSKR TPF IFA 
L02.9 37 1772 0,13 3 2168, 231,8 370 911 52 90 

SMD (%) — The sum of each item in the DEMD column. This 
represents the total demand put on the system over the 
interval, 

5E" GRDY BRDY SWPR DSKR DSKW RPQW OTHR (%) -- These 
Wvaiues represent the average percentage of the DEMD time 
that the jobs were in these states. 



TOPS-20 Monitor Internals Page 7 " 22 

WATCH 

IMEM (SUM) — The summation of. all IMEM per-job values. This sum 
is significant as an indicator of how ™*»v working sets 
belonging to processes active during the interval were 
simultaneously in memory. Tor instance, the value 4102,9% 
indicates that approximately 41 working sets belonging to 
active processes were simultaneously in memory. This number 
can be compared with NWSMi. 

NLD (SUM) — This is the number of working sets loaded during the 
interval. It should correspond to the rate given by the 
variable NLODS. 

NRSP (SUM) — The number of responses counted for all jobs during 
the interval, 

RESP CAV5 « The average response time for those J«P° n "S 
measured (requiring less than two seconds of CPU time) 
during the interval. 

SR (AV) -- The average stretch ratio for all interactions 
requiring less than two seconds of CPU time. 

wss — The arithmetic sum of the WSS values for all jobs. This 
represents the maximum amount of memory that would have been 
required during the interval If all active processes 
achieved their largest size at the same time and were all in 
memory. 

UPG5 CAV) — The average number of. pages needed by the active 
processes at any specified point in time, 

SWPR (SUM) — The total number of swap reads done by jobs on the 
system in response to page faults. This does not include 
pages preloaded by the working set manager. 

DSKR (SUM) — The total number of disk pages read that caused 
processes to wait* 

TPF (AV) « The average time required to wait for a page fault 
(swap or disk) to be resolved. 

IFA (AV) — The average amount of compute time a job spends 

between page faults. 
Additional system Variables and Computations 

The information in this display includes additional system 
statistics not available In the system statistics display and 
computations of various other variables. The following is an 
example* 

TOTRC: 1992 LOKPGS: 104 SHR PGSl 245 AVAIL MEM: 1888 
NRUN MIN,MAX» 1 11 

SUMNR MXN,MAX: 1879 2073 
NRPLQ MIN,MAX: 28 170 
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SYMEM DMD = 255,2 

SWW RATIO (SUM WSS / AV MEM) = 1,15 

ACTIVE SWAP RATIO CDMD/AVMEM) a 0,14 

MEM UTILIZATION ( (UPGS+SHRPGS)/AVMEM) ■ 0,25 

AV WS SIZE s 28,84 

AV CPU TIME (MS) PER INTERACTION s 40,57 

THINK TIME (SEC) PER INTERACTION 9 1,43 

roTRC « The number of physical memory pages available. This Is 
the total physical memory minus the number of pages required 
by the resident monitor, 

JOKPGS — * The current number of pages locked down by the monitor 
beyond the resident monitor pages. Out of this set of pages 
comes the terminal buffers, magtape buffers, line printer 
buffers, and. other pages locked down during certain file 
system operations, 

3HR PGS -- The number of pages of physical memory being shared by 
more than one process at the end of the interval. This is 
included in the count "AVAIL MEM", 

WAIL MEM — The difference between "TOTRC" and "LOKPGS". This 
is the actual number of pages available for use by user 
programs, 

IR,^ MIN, max -« The minimum and maximum number of simultaneously 
active processes during the interval, 

iUHNR MIN, MAX — The minimum and maximum number of pages 
belonging to working sets in memory during the interval, 

IRPLO MIN, max: -- The minimum and maximum number of pages on the 
replaceable queue during the interval, 

(YS MEM dmd •« The system average memory demand derived by 
computing the integrals of the memory forecast for each 
process during its active period, summing over all processes 
and dividing by the interval time. Whereas the "system 
summary UPGS" is the average amount of memory actually in 
use at any point in time, this value is the average amount 
forecast at any point in time, 

WAP RATIO (SUM WSS / AV MEM) — The swap ratio is the system WSS 
divided by the amount of available main memory. If this is 
greater than 1, it represents the amount by which main 
memory would have to be increased to avoid any swapping, 

CTIVE swap ratio (dmd/avmem) — The active swap ratio is the 

system average memory demand divided by the amount of 

available main memory. If this number is greater than 1, it 

represents the amount by which main memory would haVe to be 

<*^ increased to hold all jobs wanting to run simultaneously. 
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HEM UTILIZATION C (UPGS+SHRPGS)/AVMEM) « The memory utilization 
is the number of system-used pages divided by the amount of 
available main memory, For active swap ratios greater than 
1, this indicates how well the monitor is doing in Keeping 
memory used* 

AV WS SIZE - The average working set size is calculated from the 
integrals computed from the working set demands over tne 
active period of each process divided by the sum of the 
active periods of each process. 

AV CPU TIME (MS) PER INTERACTION « The average amount of CPU 
time a job spends between each response, 

THINK TIME (SEC) PER INTERACTION — The average time spent by the 
user between the time the system requests a response and 
when that response is received. 

The system utilization portion of data record type 05 Is shown 
under the "Disk I/O Statistics'' section below. 



7.1,4.10 Disk I/O Statistics - 

The following is an example of the disk I/O statistics display; 



CHN, 


UNIT 


SEEKS 


0,6 




380 


0,7 






1,0 




49 


1.1 




2 


1,2 






2,3 




57 


2,4 






2,5 




602 



DISK I/O 

READS 
485 

185 
6 

68 

652 



WRITES 
300 

34 



32 
449 



PS #1 
REL4 #0 
SNARK #0 
LANG #0 

MISC #0 

PS #0 



These statistics display the following information! 

CHN, UNIT « The channel number and the unit number on the channel 
to which the disk is connected, 

SEEKS « The number of times the disk heads had to be moved to 
get to the next request during the interval. If multiple 
requests can be answered on the same cylinder, no seek will 
take place, 

READS — The number of pages read on this unit during the 
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interval. 

URITES — The number of pages written on 
interval. 



this unit during the 



fhe last column shows the name of the structure and its 
unit number within the structure. 



relative 



lata record type 05 contains the information from three displaysi 
lirectory cache, system utilization, and disk I/O statistics, 
'he following shows the format of these records? 



Item 



Length Picture 



1, Record Type 2 

2, Record Sequence Number 3 

3, Date & Time 17 

CMM/DD/YY HHJMM:SS) 

4, Interval 7 

5, Number of Jobs 3 

6, Dir Cache Hits 6 

7, Dir Cache Misses - Full 6 

8, Dir Cache Misses - New Entry 6 

9, TOTRC 5 

0, LOKPGS 5 

1. SHR PGS 5 
2~jVAIL MEM S 
3r"NRUN MIN 5 

4. NRUN MAX 5 

5, SUMNR MIN 5 

6, SUMNR MAX 5 

7. NRPLQ MIN 5 
NRPLO MAX 5 

9, SYS MEM DMD 7 

0, SWAP RATIO 8 

1. ACTIVE SWAP RATIO 8 

2. MEM UTILIZATION 8 

3, AV WS SIZE 8 
i, AV CPU TIME 8 
5. THINK TIME 8 
5. Disk I/O 

Max 15 entries; 

each entry as follows 

a. Channel 2 

b. Unit 2 

c. Seeks 6 

d. Reads 6 

e. Writes 6 

f. Name 10 

g. Number 2 
'. Number of Disk I/O entries 2 



8 



99 

999 

X(17) 

9(5).9 

999 

9(6) 

9(6) 

9(6) 

9(5) 

9(5) 

9(5) 

9(5) 

9(5) 

9(5) 

9(5) 

9(5) 

9(5) 

9(5) 

9(5) 

9(5) 

9(5), 99 

9(5).99 

9(5),99 

9 (5), 99 

9(5),99 



99 

99 

9(6) 

9(6) 

9(6) 

X(10) 

99 

99 



9 
99 



Total 667 Characters 
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7.1,4.11 Tune Mode Statistics - 



Tune Mode is designed to display on one line some of the more 
interesting statistics so that a system programmer can easily 
monitor the changes in load during a test period. This mode is 
useful when a very short interval is desired (around 10 seconds). 
The Information is abstracted from the system statistics and 
system utilization statistics displays and includes the following 
variables} 



USED SWPW SKED CTXS WAKE TDIO NRUN 
52,8 2,4 6,8 41,2 16.6 13.1 2.2 



NWSM NLOD USED 
62,5 6,87 34,8 



GRDY BRDY SWPR DSKR DSKW RPQW OTHR 
41,7 2,3 19,5 1.8 



IMEM 
2207,9 



NLD 




NRSP 
198 



RESP 
0,05 



SR 
2 



The definition of the variables on the first row can be obtained 
from the system statistics display and the definitions on the 
second and third rows from the system utilization statistics 
display. 



The form of the tune mode data record 
follows: 



(record type 063 is as 



Item 



1. 


Record 


Type 






2. 


Record 


Sequence 


Number 


3, 


Date S. 


Time 








(MM/DD/YY HHJMM 


:SS) 


4. 


Interval 






5, 


Number 


of Jobs 






6, 


USED 








7. 


SWPW 








8. 


SKED 








9, 


CTXS 








10, 


WAKE 








11. 


TDIO 








12. 


NRUN 








13. 


NWSM 








14. 


NLOD 








15, 


USED 








16. 


GRDY 








17, 


BRDY 








18. 


SWPR 








19. 


DSKR 








20. 


DSKW 








21. 


RPQW 









Length Picture 

2 99 
999 
X(17) 

9(5). 9 
999 

9(4). 99 
9(4). 99 
9(4). 99 
9(4). 99 
9(4), 99 
9(4), 99 
9(4). 99 
9(4).99 
9(4), 99 
5 9(3). 9 
5 9(3). 9 
5 9(3),9 
5 9(3). 9 
5 9(3). 9 
5 9(3). 9 
5 9(3). 9 
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22, OTHR 5 9C35.9 

23, IMEM 6 9(4),9 

24, NLD 4 9(4) 

25, NRSP 5 9C5) 

26, RESP 6 9C3K99 

27, SR 3 999 

mm** 

Total 159 Characters 



CHAPTER 8 
WORKING SET SWAPPING 



.1 WQEKINfl SEX SJUeSIUG 

ith TOPS-20, the working set of a process can be brought in with 
he overhead pages (preloading) and is removed upon being 
elected to be removed (postpurging) , Postpurging of process 
orking sets always occurs. Preloading is not done by default; 
u* \s a parameter that can be set by the administrator* If 
r«w>ading is not done, the process page faults its pages in much 
he same way as it did previous to Release 4, 



.1.1 WORKING SET DATA BASE 

he information about the fork's working set is kept in a 
28-word table in the PSB, This table is the working set cache, 
ach word contains four, nine-bit entries for a total of 512 
ntries. An entry appears as follows! 



1 




1 

• 




I 




! 




1 


1 

V 


V 


1 

■ 


u 


: 


Section 


1 


Page 


i 


\ 




1 

• 




i 




• 




i 



here: 

V indicates whether the entry is valid, 

u indicates whether the entry is a user page or a 
monitor page. 

Section indicates which section this page is in. 
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Page 



is the higher-order two bits 
this page. 



of the address of 



The lower-order seven bits of the page number are used as an 
index into the table. There can be conflict since pages with the 
same lower-order seven bits will have the same index. For this 
reason there are four entries at each index. If the number of 
conflicts exceeds four, the word is shifted left one entry. The 
leftmost entry is lost and the new entry is added on the right. 
This way the four most recent entries are "remembered. " 

Much of the information pertinent to the working set swapping of 
a particular fork is contained in the table FKSWP, This table, 
indexed by fork, contains a flag that indicates whether the 
fork's working set is in memory as well as whether other types of 
information are used to determine a fork's eligibility to be 
swapped in or out. 



FKSWP: 



i 



+-■ 

! 

! 

i 

\ 
+«. 



flags I 



FKGOLN 



FKHST 



I 
•+ 

i 

I 

i 

! 
\ 

• + 



12345678 17 18 

1 1 I ! J I I FKGOLN 1 



35 



> + 



+• 
i 



FKHST 



Sy&boJL aits 

FKWSL 

FKBLK 1 

FKIBS 2 



BSWTB 


3 


BSNSK 


4 


BSCRSK 


5 


FKIBH 


6 


FKBSHF 


7 



Contents 

Working set loaded -- 
of the fork is loaded 
Fork blocked — on if 
on the wait list; off 
GOLST 

Fork in balance set - 
balance set (note tha 
necessarily in memory 
Balance set wait — o 
set (short-term, i.e. 
NOSKED — on if fork 
actually running 
Critical section — o 
and not actually runn 
In balance set hold - 
balance set since las 
In balance set hold - 



on if the working set 

fork is blocked and 
if the fork is on the 

- on if fork is in 
t it is not 
) 
n if fork is in balance 

page fault) wait 
is NOSKED and not 

n if fork Is CRSKED 
ing 

- on if fork entered 
t update to history 

- local to AJBALS 
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FkKln 8-17 GOLST position 

FKHST 18-35 Fork history — value based on the recent 

history of the for*, particularly whether 
fork has been in the balance set or not 



9,1,2 IMPLEMENTATION 

Two areas of interest in the implementation of working set 
swapping are 1) the process of deciding which processes should be 
swapped in or out, and 2) the mechanics of maintaining a working 
set. 



3,1,2,1 swapping In/Out - 

the working set manager must maintain enough available memory for 
sr- "esses to run, but it Is desirable to keep in memory poorly 
sewed processes that block and unblock frequently to minimize 
swapping. To accomplish these goals, a fork's history is 
naintained, 

The history (FKHST) of a fork Is calculated periodically 
(currently twice a second) in the routine STEPFH using the 
following algorithm: 

FKHST (old) *(STEPC-1) C+400000 (octal) if FKIBH] 

^KHST (new) = STEPC 

there* 

FKHST (new) is the new history value of the process 

FKHST (old) is the previous history value of the 
process 

STEPC is a time constant used to control the rate 
of change; currently set to 8 

400000 (octal) Is added if FKIBH is set, which Indicates 
that the process was In the balance set during 
the previous interval 

•h**larger the history value, the more recently and to a greater 
sxtent a process was In the balance set. This favors keeping the 
>rocess' working set in memory. 
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To determine which working sets to Keep in memory, which working. 
sets to remove from memory, and which working sets to bring into 
memory, the working set manager calculates a value for each 
process. This value is calculated by tallying points of a 
process based on its characteristics. If a process has a 
specific characteristic, it gets the points indicated by that 
characteristic. The value's calculation is based on the 
information contained in the following tablet 



Item 

CUecfcsd 

PUMP 



BSNSK 
BSCRSK 
FKQN 
FKIBS 



Cbacactejcistic 

Priority interrupt 
bump 

NOSKED 

Critical section 

On priority queue 

In balance set 



Value 
Added 


Symbol 
Eoc Ualue 


40, ,0 


FHMBIP 


4000,, 


FHMNSK 


100, ,0 


FHMCSK 


400, ,0 


FHMPQ 


200, ,0 


FHMBS 



If not runnable (based on the value FKBLK) add FKHST 

(history). 

If runnable (FKBLK again) add FKGOLN (G0LST position),, 

If memory is overloaded, remove the working set of the process in 
memory with the smallest value. 

If the largest value for a process not in memory Is greater than 
the smallest value for a process in memory, try to bring the 
largest process not in memory into memory, 



8,1,2,2 Mechanics Of Maintaining The working Set - 
The following operations must be able to occur: 

1, Working set swapped out: 

The swapping-out is handled in a straightforward manner; 
the working set is selected and most of the mechanics is 
handled using the same code as XGC, the local garbage 
collection, 

2, working set swapped ini 

Swapping-in is handled by first getting the overhead 
pages for the process (PSP, UPT, and JSB), if necessary. 
Then, the working set is swapped in based- on the working 
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set table (that was being used the last time the process 
was running), 

3, working set table updated as pages are used* 

Maintenance of the working set table occurs in two major 
areas. When a process page faults, the page is added to 
the working set table by the page fault code, XGC 
(local garbage collection) now scans the working set 
cache to decide which pages to remove. 



CHAPTER 9 
SYSTEM DEBUGGING 



M INTRODUCTION 

'his document contains information pertinent to debugging. Some 
>f It Is relevant mostly to crash analysis. The last section 
tontains information about MDDT, EDDT, and FILDDT, 

nalyzing a crash is different than debugging a crash. Analysis 
ells you what happened and debugging tells you why (and thus, 
iow to fix it). The information here can help you analyze what 
appened, 

u%p*ssful crash analysis depends heavily on how well you know 
he data base and whether you can discover inconsistencies that 
ive you clues about what happened, there are some basic things 
hat help you look at any crash. The information in this 
locument shows you how to use available tools to look at a crash 
md how to find basic information about the state of the machine 
it the time of the crash. Further analysis of a crash requires 
hat, based on the state of the data base, you are able to 
ropose a reason for what happened that matches the state of the 
lata base. 



,2 CTY OUTPUT 

ollect any CTY output that is relevant to the crash. This 
hould include the KLERR printout and the BUGHLT (as well as 
ecent BUGCHKs and BUGINFs), if any. If the machine got a 
EEP-ALIVE CEASED, then the KLERR output is the only reliable 
nformation you get (in release 3A), See the section on the 
UGHLT location for an explanation of why this is true. 
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9,2,1 Explanation Of KLERR Output 

KLERR Includes the PC, the last memory fetch and Information on 
the Pi system. The PI Information Includes the following: 

PI STATEJ ON or OFF —indicates whether the 

PI system Is on or not, 

PI 0N8 n — n indicates which of the 

7 channels are enabled, 

PI HLDi n — n indicates which of the 

7 channels have an 
interrupt in progress, 

PI gen: n — n indicates which of the 

7 channels have a pending 
interrupt. 

Here is an example of the KLERR output on a KEEP-ALIVE CEASED 
error: 

%DECSYSTEM-20 NOT RUNNING 



KEEP ALIVE CEASED 

KLERR — VERSION V02-02 RUNNING 

KLERR — KL NOT IN HALT LOOP 

KLERR — KL ERROR OTHER THAN CLOCK ERROR STOP 

KLERR — KL VMA: 000000 035717 PC: 000000 035717 

KLERR — PI STATE: ON, PI ON: 177, PI HLD: 004, PI GEN: 001 

KLERR « EXIT FROM KLERR 



9,3 GETTING A DUMP 

DUMP, EXE is a pre-allocated file Into which SOOT writes the dump. 
When the system comes up, SETSPD copies DUMP, EXE to DUMP.CPY, 



9,3,1 How To Get A Dump 

If the system does an auto-reload, the console front end will 
give BOOT the commands to get a dump. If the auto-reload doesn't 
wor* for some reason, you can force a dump as follows: 

KLI — VERSION VB06-07 RUNNING 



COPS-20 Monitor Internals Page 9-3 

SETTING A DUMP 



KLI -- ALL CACHES ENABLED 

KLI — BOOTSTRAP LOADED AND STARTED 

?DUPL STR UNI7DUPL STR UNI/problem because two PSi 

^structures on line, 
BOOT>/d ;request a dump (after the 

;problem is corrected), 

BOOT> Itype CR for default monitor 



>,3,2 Where BOOT Lands 

?he console front end loads BOOT into KL memory. Of course, this 
•verwrltes whatever used to be in that part of memory, 
'herefore, BOOT is always loaded into a part of the monitor that 
:ontalns pure code (i.e., so no data is destroyed) i currently 
lOOT is brought in on top of part of APRSRV, If you need to look 
it code that is loaded where BOOT lands, you have to go to the 
istings. BOOT also uses some of high core to build the EXE 
Urectory for the file dump.exe. 



.^SYSERR 

,4,1 Overview Of SYSERR Functions And Data Base 

YSERR is a program that reads PSt<SYSTEM>ERROR.SYS and generates 
eports on hardware errors, system crashes, front end reloads, 
tc. Entries in the file ERROR. SYS are written via the SYERR 
SYS, For a description of each of the types of entries, see the 
onitor tables, 

hen an ERROR, SYS entry is desired, the caller (which is one of 
he system programs such as QUASAR or the monitor Itself) builds 
SYSERR block as described in the monitor tables and does, the 
YERR JSYS, The SYERR JSYS adds the block to a queue In the 
onitor's address space; the queue header is SEBQOU (location 
4), Then it wakes up the job task which processes the queue 
nd writes the queued entries to ERROR, SYS, 



,4,2 Queued SYSERR Blocks In A Crash 

BUGHLT entry is generated when the system BUGHLTs; this entry 
s queued- but not written to ERROR.SYS, The system is considered 
o be in an unsafe state at the time of the crash. When the 
ys fc *m comes back up, code in SETSPD is called to move any queued 
YWR blocks In the dump to ERROR.SYS, 
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The queue header is location 24 (called SEBQOU);. each SYSERR 
block consists of the standard SYSERR header followed by the 
information in the specific block type. 

Sometimes it is useful to look at the queued SYSERR blocks in, a 
crash, particularly the BUGHLT block. The BUGHLT block contains 
certain status information at the time of the crash. The status 
words are described belowi 

1, CONI APR, 

Read the status of the processor error and sweep flags. 
This information is stored in offset BG%APS of the 
BUGHLT block. The flags and status information returned 
by a CONl APR, are described on page 3-59 of the 
Hardware Reference Manual, 

2, CONI PAG, 

This information is stored in offset BG%PGS of the 
BUGHLT block, A CONI PAG reads the system status of the 
pager. If TOPS-20 pagins is on, there is a 1 In bit 21, 
Bits 23-35 contain the contents of the EBR (the address 
of the EPT), For a description of all the fields, see 
page 3-4i of the Hardware Reference Manuai. 

3, DATAI PAG, 

This information is stored in offset BG%PGD of the 
BUGHLT block, A DATAI PAG returns the process status of 
the pager, DATAI PAG, returns the current and previous 
contex AC blocks, and the address of the UPT, For a 
complete description of the fields returned by a DATAI 
PAG, see page 3-42 of the Hardware Reference Manual. 

4, CONI PI, 

This information is stored in offset BG%PI5 of the 
BUGHLT block, .A CONI PI returns the status of the 
priority interrupt system; it indicates which levels 
are on, whether the PI system is on, and on which levels 
interrupts are currently being held. For a complete 
description, see page 3-7 of the Hardware Reference 
Manual, 



9,4,3 Moving SYSERR Blocks From A Crash To ERROR, SYS 

As stated before, 5ETSPD moves queued SYSERR blocks from the 
crash to ERROR, SYS, A Job task starts the SETSPD program at 
START3; this code copies DUMP. EXE to DUMp.CPY and then issues a 
SYERR JSYS for each queued SYSERR block in the crash. 
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.^BUGHLT 

ocation BUGHLT contains the location the BUGHLT came from. That 
ocation contains an XCT BUGHLT-name, All BUGHLT code is 
enerated by the BUG macro which is defined in PROLOG, 



,5.1 BUG Macro 

EFINE BUG CTYP, TAG, STR, REGS, %NAM,%STR)< 
XCT CTAGM JSR BUG'TYP 

IRP REGS,< 
Z REGS> 
SIXBIT /TAG/3 

.psect bgstr 
str: asciz \str\ 
.endps bgstr 
.psect bgptr 
xwd tag,%str 
.endps bgptr 

his is an example of a call to the BUG macros 

»jlrtLT,J0NRUN,<dOB NOT RUN FOR TOO LONG, PROBABLE SWAPPING HANGUP 

f a JONRUN BUGHLT occurred, then the data base would look like 
hist 

BUGHLT/ CAIA CLK2+6 jaddress the BUGHLT came from 

CLK2+6/ XCT JONRUN jgenerated by BUG macro 

JONRUN/ JSR BUGHLT 

/ SIXBIT \J0NRUN\ 



.5,2 BUGHLT Contents 

ocation BUGHLT is set up with the location the BUGHLT came from 
f the machine BUGHLTed, That location contains an XCT 
UGHLT-name. All the BUGHLT's are listed in the OPERATOR'S GUIDE 
ith a short descriptive phrase, 

f there is a zero in location BUGHLT the machine probably got a 
EEP ALIVE CEASED, This happens if you get either a "clock error 
to-" or "deposit/examine failure". Both of these errors are 
ai^are failures and Field Service should be called. Although 
hese two errors are the most likely cause of keep alive ceased, 
ou cannot rule out the possibility of a software bug. Get the 
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KLERR output from the CTY. It will have the PC and PI state. 

Note that because the console front end just does a reload for a 
KEEP ALIVE CEASED, the information in the dump is not dependable. 
This is because the cache has not been written out, the Ac's have 
not been saved, etc, J these things are normally done by the 
BUGHLT code. The only valid information is the CTY output from 
KLERR. 

For mere information on release 4 changes, refer to the chapter 
"Bug'Typ Macro Changes for version 4 of TOPS-20", 



9,5.3 Creating Your Own BUGHLT 

If you should desire the machine to stop in a certain state and 
save the information in a dump to allow later examination, you 
may want to create your own BUGHLT or BUGCHK, To patch a BUGHLT 
into the monitor, follow these steps: 

In the patch are, create the BUGHLT information that is generated 
by the BUGHLT macro. Its format is J 
BUGHLT name/ JSR BUGHLT 

/ , ;addresses of any locations 

fwhose contents are to be 
;dumped Cleft half must be 
;zero) 
/bughlt name in Sixbit 

Redefine the patch area to begin after the BUGHLT information you 
Just created. 

Use the DDT patch facility to insert the code to check for the 
condition you wish to cause a BUGHLT. 



9.6 PUSH DOWN LISTS AND RELATED DATA BASES. 

The push down list tnat is currently in use implies generally 
what was going on. For example, if the scheduler was running, 
SKDPDL Is the push down list, IF a page fault was In progress, 
TRAPSK is the push down list. Also, the former P Is saved. 



9,6.1 how To Look At A Stack 

i, P contains the current stack pointer, 

2, If an entry was made on the stack by a PUSHJ, then it 
will look like a PC. This isn't a hard and fast rule, 
but it can help, A user mode PC ususally has bits 1,2, 
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and 3 on and a monitor PC has bits 1 and 2 on, 

3, If a return address is still on the stack (i.e., has an 
address less than the stack pointer), then you haven't 
returned from the routine, 

4, The monitor uses the stacK for temporary storage. The 
macros STKVAR, TRVAR, etc, leave recognizable things on 
the stack. Knowing these conventions helps you to 
recognize which stack loactions are being used as 
temporary storage. 



,6,2 Push Down List/ Machine State 

he monitor uses different stacks to do different things, 
egister P is the current stack pointer and indicates which stack 
as in use at the time of the stack. The stacks and their uses 
re listed below: 

1, UPDL -• Used when running in exec mode for the user, 
i.e, doing a JSYS, Also used by the Job tasks that 
run in exec mode, 

2, TRAPSK — used for page fault handling, 

3, PIPDB — Used for software interrupt handling, 

4, SKDPDL — Used by the scheduler for the overhead cycle, 

5, DTESTK — DTE interrupt level stack (PI level 6), 

6, PHYPDL « Used by PHYSIO when queueing and IORB, 

7, PHYIPD — Used when PHYSIO is handling an interrupt, 

8, mempp — Used when handling APR interrupts. 



,6,3 Stack Usage For Local Storage 

here are several macros that provide local storage? they use 
he stack. What they put on the stack is usually recognizable, 
ee MACSYM.MEM for further information, 

1, STKVAR 

STKVAR uses the stack as temporary storage; the local 
variables have names that are really stack locations, 
STKVAR uses n stack locations for local variables where 
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n is the number of local variables requested, a count of 
local variables, and the return addres .STKRT. On the 
stack you will seet 

/ local variable 
/ local variable 
/ . 
/ . 

/ local variable n 

/ n,,n jcount of local variables 

? (used to adjust the stack 
/ .STKRT /routine to clean up the 

;stack and return 
Therefore, when you find .STKRT on the stack, the word 
before it is the count of local variables and tells you 
how many locations on the stack are in use by STKVAR. 

2, TRVAR 

TRVAR uses the stack much the same way as STKVAR but it 
also uses AC15; this is pushed on the stack first. The 
stack locations it uses look like this: 



/ 
/ 
/ 
/ 
/ 
/ 


AC15 

local variable 

local variable 

• 

• 

local variable n 


/ 
/ 


n,,n 
.TRRET 



Therefore, when you find .TRRET on the stack, the word 
before it is the count of local variables and register 
16 is stored on the stack in front of the local 
variables. 

3, ASUBR 

ASUBR saves AC15, AC'S 1-4, followed by the return 
address .ASRET, which is a routine to clean up the 
stack. When you see the address .ASRET on the stack you 
can expect the following in this part of the stack: 

/ AC15 
/ AC1 
/ AC2 

/ AC3 
/ AC4 
/ .ASRET 
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4, ACVAR 

ACVAR can save AC5, ACS and ACS, AC5-AC7, AC5-AC10, or 
AC5-AC14, depending on the arguments given. In each 
case, the return address to clean up the stack is the 
last item pushed on the stack by the ACVAR macro; the 
return address stored on the stack is the clue to what 
else was pushed on the stack. Each of the possible 
cases is listed below: 



1. AC5 saved 



/ AC5 

/ ,SAVl+2 /return address 



2. AC5 and AC6 saved 



/ ACS 
/ AC6 
/ .SAV2+3 jreturn address 



3, AC5, AC6, and AC7 saved 

/ AC5 
/ AC6 
/ AC7 
/ .SAV3+4 ;return address 



ACS, AC6, and AC7 saved 
/ ACS 
/ AC6 
/ AC7 
/ AGIO 
/ .SAV4+5 ;return address 



5, AC5 through AC14 saved 



/ 


AC5 


/ 


AC6 


/ 


AC7 


/ 


AC10 


/ 


ACll 


/ 


AC12 


/ 


AC13 


/ 


AC14 


/ 


.SAV8+7 



j return address 
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5. SAVEAC 

SAVEAC takes a list o£ AC'S to be saved as an argument. 
It pushes the list of AC'S on the stack, followed by the 
address of a literal which is the routine that restores 
the stack. One of the instructions in the literal does 
a SUB P, CNAd , ,NAO . This macro does not leave such 
easily recognizable data on the stack, but if you find a 
return address on the stack that is a literal that does 
the following, SAVEAC was used. If you look at the code 
in the literal, you will be able to tell which AC'S were 
pushed on the stack and how many there are (,NAC is the 
count of AC's pushed). The stack is left like this/ 

/ AC 

/ AC 

/ . 

/ • 

/ last AC saved 

/ address of literal to restore stack 

The literal to restore the stack looks (approximately) 
like this: 

LIT= address of literal to restore stack 
for this example, 

LIT-i/ 3, ,3 /count of AC'S saved =3 

LIT/ CAIA 

/ AOS -N(P) 

/ MOVE 1,-2(17) /restore AC1 

/ MOVE 5,-1(17) /restore AC5 

/ MOVE 10,0(17) /restore AC10 

/ SUB 17, LIT-1 /reclaim stack locations 

/ POPJ P, /return to calle? 



6, SAVEP 

This macro calls the routine Savp (in APRSRV) to save 
the AC's P1-P6 on the stack followed by the address 
RESTP, which is the routine to restore the AC'S, 



/ 


PI 


/ 


P2 


/ 


P3 


/ 


P4 


/ 


P5 


/ 


P6 


/ 


RESTP 
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7, SAVEQ 

This macro calls the routine SAVQ (in APRSRV) to save 
the AC'S Q1-Q3 on the stack, followed by the address 
RESTO, which is the routine to restore the AC's, 

/ Qi 

/ 02 

/ 03 

/ RESTO 



8, SAVEPO 

This macro calls the routine SAVPQ (in APRSRV) to save 
the AC's Q1-Q3 and P1-P6 on the stack, followed by the 
address RESTPQ, which is the routine to restore the 

AC'S. 

/ 01 

/ 02 

/ 03 

/ PI 

/ P2 

/ P3 

/ P4 

/ P5 

/ P6 

/ RESTPQ 



9. 5AVET 

This macro calls the routine SAVT Cin APRSRV) to save 
the AC's T1-T4 on the stack, followed by the address 
RESTT, which is the routine to restore the AC's, 

/ Tl 

/ T2 

/ T3 

/ T4 

/ RESTT 



•6.4 Stack Adjustment 

any times the stack pointer is adjusted. Table BHC, indexed by 
, contains n,,n which may be added to or subtracted from the 
tc , pointer. 



TOP5-20 Monitor Internals *•«• 9 " 12 

MACHINE STATES AND RELEVANT DATA BASES 

9.7 MACHINE STATES AND RELEVANT DATA BASES 
9.7.1 . PC Storage 

1, PC at the time of the crash 

Location BUGHLT contains the PC at the time of the 
crash. 

2, PC when JSYS began 

Two copies of the PC are saved on the stack. 

3, PFL/PPC 

Current PC of process when the process was last context 
switched. Can be exec or user mode PC. 

4, PIFL/PIPC 

Exec mode PC saved here while the software interrupt 
code is in progress. 

5, Temporary PC storage 

When the system is changing state, it must always be 
prepared for a context switch. This is a concern when a 
JSYS Is starting, when a process blocks, and when a 
software interrupt begins. In each case, the PC is 
temporarily stored in case of a context switch while the 
state change is in progress, 

1, SKDFL/5KDPC - PC saved here while process is 
blocking. 

2, MONFL/MONPC • PC saved here while nested JSYS is 
starting. 

3, ENSKR/ENSKR+1 - PC saved here while entering the 
scheduler via the ENTSKD macro. This is the PC the 
ENTSKD macro was called with. 



9,7.2 AC Storage 
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.'1.1 AC Storage In The PSB - 

ach process's PSB contains several storage areas for saving 
C's, AC'S are saved in the PSB in these cases! 

1, Nested JSYS (JSYS called by a JSYS) 

When a user called JSYS is in progress, AC bloc* 
contains the monitor's AC'S (the current JSYS code AC's) 
and AC block: i contains the user mode AC'S. If the JSYS 
code does a JSYS, AC block; 1 (user mode AC's) are saved 
in the UACB area and the AC block AC's are moved to AC 
block i. For each level of JSYS, the AC block: i AC's 
are pushed onto the UACB stack: and the AC block AC'S 
are moved to AC block i. Therefore, the AC block 1 AC's 
are always the previous context AC's? i.e., the AC's 
when the JSYS was called. 

If a nested JSYS is in progress, then the user mode AC's 
are the first stacked AC's In UACB, If the nesting is 
more than one level deep, then each subsequent JSYS's 
calling Ac's are also saved In UACB? the current JSYS 
AC's are saved in UAC if the process is not currently 
running or in BUGACU if the process was running at the 
time of the crash. The maximum nesting level for JSYS's 
is 5? this limit is dependent on how much storage is 
reserved for AC stacking In UACB, 

ACBAS Is the "pointer" for the AC stack UACB, but Is not 
stored as an address. The contents of ACBAS must be 
shifted left 4 places to make it an address. The 
resulting address is the first saved AC for the last 
pushed AC block? i,e, the saved AC'S for the next 
higher level of nesting. If there are no saved AC's 
pushed on the stack, ACBAS contains its Initial value of 
<UACB>B39-i=37677? if ACBAS contains anything else, 
there are pushed AC blocks saved in UACB, 

2, Process is context switched while running In user mode. 

The current AC'S Cl.e,, the user mode AC's) are saved in 
block UAC, 

3, Process is context switched while running In exec mode. 

The current AC's Cl.e,, the exec mode AC's) are saved In 
block PAC, The previous context AC's are saved in block 
UAC, The AC's saved in UAC are the user mode AC's 
unless a nested JSYS is in progress? in this case, the 
AC's saved in UAC are the AC'S the nested JSYS was 
called with. The user mode AC's for this case are saved 
on the AC stack called UACB? the user mode AC's are the 
first saved AC'S on UACB. 
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4, Software interrupt processing 

The exec mode AC'S are saved in block: PIAC while a 
software interrupt is in progress. 



9,7,2,2 AC Storage At The Time Of The Crash - 

1 , BUGACS 

Exec mode AC'S at the time of the crash. Copied to 
current AC'S when using FILDDT, 

2, BUGACU 

Previous context Ac's at the time of the crash. These 
are the user mode AC'S unless a nested JSYS was in 
progress, i,e,, a JSYS called from a JSYS, It a nested 
JSYS was in progress at the time of the crash, BUGACU 
contains the AC's the current JSYS was called with. In 
this case, the user mode AC'S are saved in the AC stack 
called UACB, 



9,7,2,3 Summary Of AC Storage « 

It "AC 

Previous context AC's are saved here when the user Is 
context switched, For the currently scheduled process, 
UAC contains the AC's the last time the process was 
dismissed, once again, if a nested JSYS was in 
progress, UAC's contains the AC's that JSYS was called 
with. In this case, the user mode AC's are saved in the 
AC stack called UACB. 

2, UACB and ACBAS 

Pushed AC blocks when nested JSYS in progress, 

3, PAC 

Exec mode AC'S saved there for process when it is 
dismissed, 

4, PIAC 

Exec mode AC's saved there when software interrupt is in 
progress. 



DOPS-20 Monitor Internals Page 9-15 

4ACHINE STATES AND RELEVANT DATA BASES 



5. BUGACS 

Exec mode AC'S at time of crash* 

6, BUGACU 

Previous context Ac's at time of crash, 

1.7.3 Fork Scheduled Or Not 

If a fork is scheduled, location FORKX contains the fork's system 
iork number. The scheduled fork's PSB and per process pages, JSB 
ind per job storage, and page table are all mapped into the 
ionitor'5 address space, if no fork is currently scheduled, 
.ocation FORKX contains a -i, 

1.7.4 Fork NOSKED 

If a fork is nosked, its fork number is stored in SSKED? if 
:here is not a NOSKED fork, SSKED contains -1, The FKSWP table 
;on*-ains status bits for both NOSKED (no other process may be 
iC^^Juled) and CRSKED, CRSKED is a new process state in release 
t for processes manipulating the monitor resident free pool, 

*.7.5 Extended Vs. Non-extended Addressing 

If the machine supports extended addressing, flag EXADDR contains 
i it if the machine does not support extended addressing, EXADDR 
contains 0. 

.7,6 sizes (resident, Non-resident, Total) 

MONCOR/ number of pages in resident monitor 
TOTRC/ total number of swappable core pages 
NHIPG/ highest physical core page number 
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9,7.7 MDDT Page (release 3A) 

When MDDT is In use for a process, DDTPPG (currently page 774) 
exists* If the running process's page 774 exists, then that 
process has been using MDDT? you might suspect that the crash 
was caused by an accidental deposit in MDDT or some such thing. 



9.7.8 Interrupt Vs. Non-interrupt Level 

9.7.9 Relevant Data Base For Each Machine State 
9.7.9,1 JSYS - 

1, Stack 
UPDL 

2, Initial stack setup 

Initial UPDL set up for JSYS if from user mode* 

/ PC at time of JSYS 

/ PC flags at time of JSYS 

/ PC at time of JSYS 

/ PC flags at time of JSYS 

Initial UPOL set up for JSYS If from exec mode (nested) 

/ INTDF 

/ MPP (for higher level JSY5) 

/ PC at time of JSYS (return PC) 

/ PC flags at time of JSYS 

•J, Previous PC 

The return PC is pushed on stack; MPP is stack pointer 
for return PC, 

4, Saved AC'S 

AC'S saved in UACB if nested JSYS, See section on AC 
STORAGE for a description of UACB, 

5, saved stack pointer 

If the JSYS was from user mode, this is not relevant. 
If the JSYS is nested, the previous JSYS also used this 
stack and the MPP pointer can be used to determine where 
the stack pointer was when this JSYS began! 
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Previous 
stack ptr-> / 

. / INTDF 
/ MPP (for higher level JSYS) 
/ HON PC 
MPP •> / PC at time of JSYS (return PC) 



6, AC usage 

There is no standard for AC usage that all JSYS's 
conform to, 

7, Related storage 

1, MPP — points tor 

—return PC for JSYS 

—last location of initial setup for this JSYS 

2, FPC s KIMUPC — dispatch address for JSYS 

3, KIMUUl - last UUO from user in format? 

KiMUUl/ flags,, opcode 
/ JSYS number 

4, INTDF 

indicates whether the process is NOINT, and to how 
many levels. Set to -i if the process is not NQINTf 
greater than or equal to zero if the process is 
NOINT, 



,7,9,2 Page Fault • 

1, Stack 

TRAPSK 

2, Initial stack setup 

The initial stack setup differs for each of three cases: 
<*-page fault from user mode 

—page fault from exec mode 

--recursive page fault 
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t, StacJc setup on page fault from user mode 

/runtime 
/return PC 
/return PC flags 

2. StacJc setup on page fault from exec mode 

/ AC1 

/ AC2 

/ AC3 

/ AC4 

/ AC7 

/ AC16 

/ TRAPSW 

/ runtime 

/ PC 

/ PC flags 

3, Stack setup on recursive page fault 

/ AC1 

/ AC2 

/ AC3 

/ AC4 

/ AC7 

/ AC16 

/ TRAPSW 

/ PC 

/ PC flags 



3, Previous PC 

Saved on stack; see initial stack setup for where, 

4, Saved AC'S 

Those AC*s that are saved are kept on the stack. See 
the initial stack setup for where each AC is saved, 

5, saved Stack Pointer 
TRAPAP 

<>, AC usage 

Differs for each type of page fault. 
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7, Related storage 

1, TRPID —Identity of page causing trap in form 
PTN,,PN or PTN 

This is the identity of the page the page fault 
handler is working on, TRPID contains the page's 
page table identity while the page's page table is 
brought into core (if the page table was not in 
core) , 

2, TRPPTR 

Storage address of the page the page fault handler 
is working on. 

3, TRAPSW (copy of TRAPSO) 

4, TRAPC 

if first level page fault; if greater than 0, it 
indicates the level of recursion, 

5, TRAPFL/TRAPPC = UPTPFL/UPTPFO 
Flags and PC at time of page fault,, 

6, TRAPSO a UPTPFW 

Page fail word; contains the address that page 
faulted. 



,7.9.3 Scheduler - 

1, Stack 
SKDPDL 

2, Initial stack setup 
None • 

3, Previous PC 

Saved in PSB for a process when context switch to the 
scheduler; the PC is saved in PFL/PPC of the process's 
PSB, If FORKX contains a fork number, it is the number 
of the fork running when the scheduler was invoked. If 
FORKX is not setup, you cannot determine which fork was 
running last. 
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4. Saved AC'S 

The process's AC'S are saved in block PAC (exec mode 
AC'S) and block UAC (previous context AC's) of the PSB 
for the process. If FORKX is not setup, you cannot 
determine which process was running last, 

5, Saved Stack Pointer 
In the saved AC's. 

6i AC usaqe 

FX/ -1 if no fork chosen or system fork 
number of chosen fork 

7. Related Storage 

1. FORKX 

FORKX contains a -i if no fork is chosen or the fork 
number of the chosen fork. 

2. Temporary storage while entering scheduler 



9,7.9,4 Physio Queueing Level « 

1, Stack 
PHYPDL 

2, Initial Stack Setup 

The P and Q AC'S are saved on the stack by the macro 
SAVEPQ; the AC's are saved in order of 01 through Q3 
followed by PI through P6. See the section on Stack 
Usage for Local storage for the format, 

3, Previous PC 

Since PHYSIO is called with a PUSHd, the previous PC is 
the top of the saved stack, 

4, Saved AC'S 

. AC's Q1-Q3 and PI through P6 are saved on the stack. 
See the section in Stack usage for Local Storage 
entitled SAVEPQ, 
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5, saved Stack Pointer 

The previous stack pointer is saved in PHYSVP, 

6, AC usage 

P4/ address of XORB being queued* 

PI/ address of CDB 

P3/ address of UDB 

P2/ address of KDB or if no KDB 

7, Related storage 

,7.9,5 Physio Interrupt Level - 

1, stack 
PHYIPD 

2, Initial stack setup 
None, 

3, Previous PC 

The previous PC is saved by the XPCW instruction in a 
two word block, beginning at the CDB-6, 

4, Saved AC'S 

PHYACS — block where AC'S saved 

5, Saved Stack Pointer 

The saved stack pointer is in PHYACS+17, 

6, AC usage 

Pi/ address of CDB 

P2/ address of KDB or if none 

P3/ address of UDB 

P4/ IQRB address or argument 
indicating action code* 
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P4<0 schedule a channel cycle 

(P4) ■ -i 
P4=0 dismiss Interrupt 
P4> houselceep current request 
(contains IORB address) 



?. Related Storage 

Home block check funtion. In STG, starts at CHBUDB, 



9.7.9.6 APR Interrupt Level - 

1. Stack 
MEMPP 

2, Initial stacic setup 

/UPTPFOa TRAPPC 
/UPTPFLa TRAPFL 
/UPTPFN 
/UPTPFW= TRAPSO 

3, Previous PC 

Saved as double word PC by XPCW in location PIAPRX and 
PIAPRX1 

4. Saved AC'S 

MEMPA « block where AG's 0-10 are saved, 

NOTE 

Beginning in 3A, uses a different AC block while 
at APR interrupt level? therefore, no AC's are 
saved. 

5, saved Stack Pointer 

memap « previous stack pointer saved there, 

6. AC usage * 



OPS-20 Monitor Internals Page 9-23 

ACHINE STATES AND RELEVANT DATA BASES 



^p.7, Related Storage 

1, Sets "local" page fail routine to MEMPTP 



,7,9.7 DTE Interrupt Level <• 

1, Stacfc 
DTESTK 

2, Initial stack Setup 
None, 

3, Previous PC 
Saved in DTETRA, 

4, Saved AC'S 

DTEACB •* block where AC's saved, 
~^w5* Saved stack Pointer 

Previous stack pointer is saved in DTEACB+17, 

6, AC usage 

F/ result of CONI DTEn, 

A/ DTE number of DTE that caused interrupt 

3/ count (if RSX20F protocol) 

4/ Byte pointer (if RSX20F protocol) 

7, Related storage 

,7,9.8 PSI Handling - 
1. Stack 

PIPDB 
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2, Initial Stack Setup 

3, Previous PC* 
PIDL/PIPC 

4, Saved AC'S 

PIAC — block where AC'S saved. 
$, Saved Stack Pointer 

Previous stack pointer is saved in PIAC+17, 

6, AC usage 

FX/ interrupt flags from fkint 

7, Related Storage 

1. How to tell if interrupt in progress 



9,7,9,9 Job Exec Mode Tasks - 
U Stack 
UPDL 

2, initial stack Setup 

3, Previous PC 

Since these are scheduled processes, this is not 
relevant, 

4, saved AC's 

Since these are scheduled processes, this is not 
relevant, 

5, Saved Stack Pointer 

Since these are scheduled processes, this is not 
relevant, 

6, AC usage 
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7, Related storage 

1, How can you ten this use of UPDL from a JSYS? 

If the FKJOB entry for the running fork is Job 0, 
then this is probably a Job task: as opposed to a 
JSYS in progress. Also, if the PC is in a Job 
routine, this indicates a Job task. 



,7,9,10 User Mode - 

he system never BUGHLTs in user model but it could KEEP ALIVE 
EASE, The PC is from user mode if the flag UMODF is set in the 
C. 



,8 DOT'S 

.8.1 FILDDT 

he ^atest version of DUMP,CPY is the last crash. The program 
Ibwi#T is used to analyze a crash. 



,8,1,1 How To Use FILDDT On A Crash • 

o look at a crash with FILDDT you need the dump and the monitor 
lie it came from (for symbols). For examples 

•ENABLE 

$FILDDT 

FILDDT>LOAD <5YSTEM>M0NITR,EXE ;load symbols 

FILDDT>GET <SYSTEM>DUMP,CPY Jload dump 

fie AC'S contain their contents at the time of the dump. By 
sfault you look at physical (not virtual) addresses. 



,8.1,2 $U Command - 

ILDDT can simulate KL paging. You can set paging using the 
ILDDT $U command. This command allows you to specify the 
Dcation of the page table different ways, depending on how much 
^formation you have .on where the page table Is, For more 
rtt. nation on the SU command, refer to the section on DDT 
erWon 41, In the part of the monitor that BOOT loads, there is 
one-to-one correspondence between physical and virtual 
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addresses; MMSPTN Is in this part of the monitor's address 
space. 

If you wish to look at some fork's address space, find, its page 
table's 5PT slot in the left half of FKPGS, indexed by fork 
number* 

If you wish to return to physical addressing (i.e., no KL paging 
simulation), type $$U, 



9.8.2 Relevant DDT/FILDDT Commands 

These are standard DDT commands; however, you may not be 
familiar with them. They are included here along with examples 
of their use. 



9.8.2.1 Question Marie (?) - 

If you type a symbol followed by a question mark, DDT tells you 
which moduleCs) that symbol appears in; the module name is 
followed by a G if the symbol is global, A local symbol may be 
defined in more than one module,, 

This facility can be used to locate symbols, like GLOB, but 
faster, 

BUGSTO? 

APRSRV ; symbol is local and defined in APRSRV 

SPT? 

STG G ;symbol is global and defined in STG 



9,8,2.2 Underscore () - 

A value, followed by underscore, is a request to DDT to find a 
symbol with that value. 

This facility can be used to locate the symbolic address o£ a 
value, 

14156.LSCHED+5 
101400_SPT 
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•\ht2.3 Effective Address Search C$E) • 

he $E command is used to search for all locations where the 
ffective address, following all indirect and index-register 
hains to a maximum length of 64, base 10, equals the address 
eing searched for, 

he format of the command is a<b>c$E; a<b> is the range and is 
ptionai. If no range is specified, the whole address space is 
ssumed. The c argument is the address to search for, 

MMSPTN$E 

PGRI10+3/ MOVEM T1,MMSPTN 
FPTA4/ SKIPA T1,MMSPTN 
MLKPGM+2/ CAMN T2,MMSPTN 
SWPER3+2/ CAMN T2,MM5PTN 
GSML'ER + 11/ HRL Tl,MMSPTN 
BSMGP1+2/ HRL T1,MMSPTN 
212777/ HRL T1,MMSPTN 
5NPF0A+1S/ HRL Ti,MMSPTN 
SNPF5B+10/ HRL Ti,MM5PTN 
UT1LL+1/ HRL T1,MMSPTN 

JSB<JSB+5>0$£ 
JOBMAP+2/ 
JOBMAP+3/ 
sJOBMAP+5/ 



.8,2.4 Word Search C$w) 



ord search compares each storage word with the word being 
earched for in those bit postitions where the mask, located at 
M, has ones. The mask word contains all ones unless set by the 
ser. If the comparison shows equality, the word search types 
ut the address and the contents of the location? if the 
omparison results in inequality, the word search types out 
othlng. 

he format of the command is a<b>c$W, a<b> is the range and c is 
he quantity searched for. To set the mask type n$M where n is 
he quantity to be placed in the mask word, 

uppose we wish to find all share pointers in the current user's 
age map between pages and 10. We want to store a 7 (for 
ointer type) in bits 0-2 of the mask. Our command is 
PTA<UPTA+10>200000,,0$W and works as follows? 

7000000, ,0$M 

UPTA<UPTA+iO>200000,,OSW 
UPTA+2/ 206000, ,1244 
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UPTA+4/ 206000,, 1242 



9,8.2,5 Not Word Search ($N) • 

Not word search works like word search, the only difference Is 
that it types out the contents of the register when the 
comparison is an inequality and types nothing when an equality Is 
reached. 

Not word search is commonly used to type out all non-zero 
locations in some range, suppose we wish to find all existint 
Cnon-zero) entries in the JSB map, 

-ISM 

JOBMAP<JOBMAP+66>0$N 

JOBMAP/ 224000, , 635 

JOBMAP+1/ 124003,, 7044 

JOBMAP+4/ 124003,, 2764 

JOBMAP+6/ 124003,, 7050 



9,8,3 MDDT 

MDDT Is a part of the monitor that allows you to look at the 
running monitor with the standard DDT commands; your process is 
always the running process when you use MDDT, You can also call 
monitor routines to map paqes, etc; however, extreme caution 
should be taken when using MDDT, If you change any locations, 
you can crash the monitor. It Is a good practice to type 
carriage return immediately after you open any location to 
prevent accidental deposits into memory. 

You can enter MDDT in either of two ways. In the first example, 
the running fork will be the top fork of your job; i.e., the 
EXEC, In the second example, the running fork will be the fork 
running user level DDT, 

3ENABLE 
$*EQUIT 
MX>/ 
MDDT 



CENABLE 

SSDDT 

MDDT%$X CJsys 777) 

MDDT 
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a^^an use either method to enter MOOT, Return from MDDT by 
ailing the routine mretn. Do this by typings 

MRETNSG 



.8,3,1 MAPPING MONITOR PAGES - 

iere is oftentimes a need to examine pages of the Monitor which 
re not currently part of its virtual address space. Examples 
Lght be the JSB or PSB of a hung job or fork or the Index Block 
E a file. The safest and easiest way to do this is to use the 
5TMPG routine (or MSETMP for a set of contiguous pages) to map 
ie page(s) into the User's address space, optionally read and 
rite or just read access can be requested. The only valid 
jason for write access would be if you Intended to change a 
acation in the mapped page in order to un-hang the job. 

The following is the setup for calling SETMPG or MSETMP* 
ACl/ Internal Identity of page 
(in form 0,,SPT index 
or 
SPT index,, Page number) 

AC2/ Access, , Address to map to 

C 500000,, XXX000 for read access 
mapping to page XXX 
or 
540000,, XXX000 if read and write 
access desired) 

AC3/ Number of Pages 

(if calling MSETMP) 

The following is an example of mapping the JSB area pages 
E a job and the PSB for a fork: 



sna 

jet <system>monitr.exe 

st 140 

)T 



;get monitor's symbols 
;ddt 



Jdt%$x 
5DT 



;go to MDDT 



'apping the. PSB 



cpgTT40[ 1672, ,1704 



;SPT Index of fork 40*s PSB 
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Til 
T21 



1704 

500000, ,psbpga 



/internal ID 
;access, , destination 



call setmpgsx 
<> 



/only one page so call 
SETMPG 



mretnsg 
<> 



;return to user 



uptpfl/ 
UPTPFO/ 
UPTPFN/ 



CAIA 

Tl, , .SFRKV+12 

PGRTRP 



/flags,,pc of fork's 
; last page fault 



fkrtl 4160 



/fork's runtime 



mddt%$x 
MDDT 

/Mapping the JSB pages for a job 



/return to MDDT 



fkjob 40[ 22, ,2152 



;get fork 40 # s JSB index 



Tl! 
T2I 

T31 



/SPT index,, page of JSB 
/access, destination 
of mapping (JSB area) 
jslsta'1000-jsbpga*1000/number of pages to map 



2152, ,0 
500000, , jsbpga 



call cnsetmp$x 
<> 

mretnsg 
<> 



/JSBPGA is the address of the first page 
/ in the JSB area (the JSB Itself) 
/JSBLSTA is the addresss of the last page 
/ In the JSB area 

/the first N locations in the JSB (where 
/ N .Is the number of pages in the JSB 
/ area) contain pointers to the JSB 
/ area pages 

/call the routine 



/return to user mode 
to see mapped pages 



jobmapt 224000, ,2152 
JSBPGA+iE 124003, ,7170 
JSBPGA+2C 



/look at first few locations 
in JSB 
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r3PGA+3t 



:ilnen mljfnt 331501 , ,331503 fpointer 
31503 C 777777, ,2 St string 

31504/ EXE 



to extension 
for first JFN 



SRNAMt 3 juser name 

SRNAM+lt 422371, ,640620 $t/DONAH 
SRNAM+2/ UE 



y GET'ing MONlTR.EXE you can map the pages to their own 
ddresses and then be able to use the defined symbols rather than 
etermining the offsets within a different page address. Since 
he pages have been mapped to the User's Address space rather 
han to the Monitor's it is not necessary to unmap them when 
one. A RESET will get rid of them. 



,8.4 EDDT 

hi**!* you are in EDDT, timesharing ceases. Only the EDDT process 
an run, 

DDT must be locked in memory. This is accomplished by one of 

he following: 

Bringing the monitor up with EDDT and setting a flag 

to request that EDDT be kept locked in memory. 

Calling the routine LCKINI from MDDT? this routine 
locks EDDT in memory and must be called BEFORE 
entering EDDT, 



,8,4,1 Debugging Switches • 

he locations described in this section can contain flags that 
re useful for debugging. The flags must be set before normal 
onltor startup; i.e. from EDDT startup. The default setting 
or each of the locations is zero, 

EDDTF 1 Keep EDDT in core when system comes 

up 
DBUGSW or 1 Stop on BUGHLTs 

2 Wrlte-enable swappable monitor, 
start up Sysjob using the file 
SYSJOB, DEBUG for the Sysjob commands 
and stop on BUGHLTs, 
DCHK5W Do not Stop on SUGCHKS 
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DINFSW Do not stop on BUGINFs 



9,8.4.2 Loading The Monitor with EDDT • 

Observe the following steps to load the monitor with EDDT locked 

in memory; 

Load the monitor and start it at location 141 CEDDT 

startup). 

Set the EDDTF flag to If this keeps EDDT locked in 
memory. The DBUGSW switch can also be set at this 
time if desired. 

Set any desired breakpoints In the resident monitor. 
Only the resident monitor is loaded; therefore you 
cannot access any part of the swappable monitor. 
The breakpoint which is usually set at this point is 
GOTSWM, when the montiro reaches GOTSWM, the 
swappable monitor is already loaded. 

Start the monitor at 147, This is the normal 
startup address. Since EDDTF is set, EDDT remains 
in memory. 

When it reaches the breakpoint at GOTSWM, you may 
wish to do one or more of the following: remove the 
breakpoint, write-enable the swappable monitor (Call 
SWPMWE), lock the swappable monitor (Call SWPMLK), 
set breakpoints, continue the monitor (SP), 

Whenever you hit an EDDT breakpoint, timesharing 
ceases until you continue from the breakpoint. 



9.8.4,3 Page Faulting In EDDT •■ 

If you reference a page that is swapped out while you are in 
EDDT, the page is NOT fauled in? EDDT types ? in this case. 
EDDT does not change the state of the system, You can cause a 
page to be brought in by typing SKIP LOCSX where LOC is some 
location in the page you wish to have swapped in. 



9,8,4,4 How To Re-enter EDDT - 

Once EDDT has been locked in memory, you may re-enter by doing 
the following: enter MDDT; type EDDTSG, If the system hangs, 
and you wish to enter EDDT: type control backslash to get Into 
the command parser; examine the PC to see where the system Is 
hung; start the monitor at location 140, If this fails, ask to 
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start at 141 to force a Reset and then enter Enoi. 



9.8.4.5 TO Leave EDDT - 

To exit from EDOT (unless In a breakpoint), type wDDTSG to 
reenter mdDT; type MRETNSG to return from the Jsys. 



a.8.5 Sendinq TOPS-20 Crash Dumps In To Be analyzed 

vnen sending vour crashes in for analysis, here are some hints 
which will ma<e the analysis easier! 

Put a copy of the dump and a copy of the monitor 
that *as running at the time of- the crash on a 
magtape. The tape should NOT be In DUMPER 
interchanae format. Use a density of 1600bpi, Put 
a second cocy of the dump and monitor on the taoe to 
minimize the possibility of read problems. 

Use the OUMPEP Print C7mmand to maKe a hard copy of 
the savesets and file names on the tpae, and send it 
with the tape. 

Include the CTY output at the time of the crash. 
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CRASH DUMPS 

acb time there is a BUGHLT there is an automatic dumping of the 
ystem core lmaoe into PSKSYSTEJODUMP.EXE. If there is sufficient 
oom on the DSK tne data that was previously in DUMP, EXE will be 
ooied into DUMP.CPY oy SETSPD after the system is reloaded, DUMP.CPY 
oes not get deleted and you may find several generations of DUMP.CPY, 

in the case you nave set no auto reload you can dump the crash by 
and by tyoing /D to the system BOOT> prompt. You can get into BOOT 
f you are reloading the system by bringing the system up from tne 
witch registers rather than hitting <ENABLE> <DISK> on the console, 
ee the Operators Guide for a discussion of the meaning of the various 

witcnes on the DEC-20, 

9-5ep-80 
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First when analyzing software or software/hardware problems be 
sure you nave the proper tools: 

i. Internals reference materials Ctables and flowcharts), 

3, A full copy of the current release microfiche MONITOR and 
EXEC, 

3, A MONITOR CALLS REFERENCE MANUAL, 

4, A 5YSERR manual, 

5, A listing of the SYSERR log, especially if hardware is 
suspected, 

6, A CTY output for BUGHLTs and BUGlNFs or other problem 
indications, or an accurate reproduction of this information, 

7t Any other manuals you may need for reference such as the 
proper version Installation Guide, Operators Guide, System 
Managers Guide, etc, 

8, A TOPS-20, BWR file. 

You will need listings of the latest versions of monitor 

modules in case the microfiche are not up to date, FILDDT is 
on the customers distribution tape. 

Be sure you have analysed the SYSERR log. Be sure, also, that 
you have looked up the BUGHLT and/or BUGCHKs in question in the 
listings (microfiche) and have at least read the comments around them, 
Probably tracing down how it got called is a good idea. If you happen 
to be without a GLOB (provided on microfiche) you can find the BUGHLT 
tag of interest In the monitor as follows: 

SGET <5YSTEM>M0NITR.EXE 

SST 140 

DDT 

ILPP3? ; BUGHLT of interest followed by "'?" 

PAGEM G ? it is defined in PAGEM and Is global 



Some other useful bits of information. There is a GLOB listing 
provided in the microfiche which contains a list of all the global 
symbols In the monitor. Most of the symbols are defined in the module 
STG.MAC, If you don't know a tag name but want to look at the storage 
for DTEs, say, look through STG, STG also contains some small portion 

9-Sep-80 
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E^C'ode mostly to do with restart, start, auto reload, dispatches for 
I channels and A few scheduler tests, STG stands for storage. Note 
nat some stuff may be defined in PROLOG, and of course lots of stuff 
5 defined throughout the monitor. You may also want to get a listing 
t MACSYM to be able to understand the macros you see while reading 
ne monitor listings; MONSYM is also useful at times. Be sure you 
iow how PARAMS has been changed in case it has. See BUILD, MEM on the 
Lstrlbution tapes for the currently distributed information on what 
3 do to change various system parameters in PARAMO, MAC, Be sure that 
3U know about any variables that the site may have changed in STG as 
ell. 

9-Sep-80 
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Debugging a complex* multl-process software system is largely a 
matter of absorbing sufficient Knowledge, experience and folklore 
about the particular system with a considerable element of personal 
preference, or 'taste' also Involved. This document Is a cursory 
description of features built into the system to aid debugging, and 
such folklore as can be described in written English, 

There are four different versions of DDT that may be used to 
examine the monitor. Each is used for a different purpose and has 
special capabllites. The versions of DDT are: 

1, UDDT (user DDT) used to examine or modify the MONITR.EXE 
file. 

2, MDDT (monitor DDT) used to examine or modify the running 
monitor under timesharing, 

3, EDDT (exec DDT) used to examine or modify the running monitor 
from the CTY in a stand-alone mode, 

4, FILDDT used to examine dumps. 

All the DDT's are versions of TOPS-20 DDT documented in the 
TOPS-20 DDT manual, and have all of the features described in the 
manual. See also the document DDT41.MEM, 

The use of all four versions of the DDT's is the same and will be 
described latter, however, each version is started differently, 

9»Sep-80 
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To use UDDT to modify your MONITR.EXE file on system, you must 
ive the following EXEC commands: 

9GET <SYSTEM>MONITR,EXE 

9START 140 or on Release 4 systems, 9DDT 

his causes EDDT to start in user mode. This is the same DDT that is 
sed when examining any program. You may now look at or change any 
art of the monitor. If you make changes to the monitor and want to 
ave it, you should get bade to the EXEC by typing *Z, Then you may 
ave the monitor. 

You will probably have to be enabled in order to save the monitor 
aclc in <SYSTEM>, This is the safest, best, and recommended method of 
utting patches into the monitor, 

9-Sep-80 
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MDDTt 



A version of DDT which runs in monitor space is available. It 
can examine and change the running monitor, and can breakpoint code 
running as a process but not at PI or scheduler level. When patching 
or breakpointing the swappable monitor, the normal write protection 
must be defeated, either by setting DBUGSW to 2 on startup, or calling 
SWPMWE, If you insert breakpoints with MDDT, remember. monitor code is 
reentrant and shared so that the breakpoint could be hit by any other 
process in the system. In this event, the other process will most 
likely crash since it will be executing a JSR to a page full of zeros. 



To use 
first issue 



HDDT you 
the EXEC 



must have 
command; 



WHEEL or OPERATOR capabilities. You 



©ENABLE 
S*EQUIT 



MX>/ 



MX>S 

MX>E 



; You are now in the mini-exec and receive a prompt 
; of MX>, now you give the "/" command: 



HRETNSG 



o the EXEC 
produces a 
eturns you 
n MDDT you 
eturned to 

mini-exec 
typing this 
xec. This 
g programs 

mini-exec 



; You are now put into HDDT, To return t 

; you can Issue a *z or a *C which 

; message like "INTERRUPT AT 17372" and r 

; to the mini-exec. If you type a *P i 

; will get a message, "ABORT", and be r 

; the mini-exec. If you once go into the 

j the CONTROL-P interrupt is enabled and 

; character will return you to the mini-e 

; is a good thing to use when debuggin 

; that do CONTROL-C trapping. From the 

; you may give either: 

; or 



? The S is filled out as START and the E as EXEC, 

; both of these commands will return you to the 

; EXEC, See the document EXEC-DEBUGGING, MEM for more 

; about *P and getting out of the EXEC to MX> and 

; returning from MX> to either your copy of the EXEC 

; or the system EXEC, 



; You may also give the command: 



; From MDDT to return directly to the EXEC, While 

} in MDDT you may examine any core location in the 

; running monitor. You may also change any location 

; in the resident monitor (done frequently by 

; accident). If you wish to change any of the 



9-Sep-80 
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; locations In the swappable monitor you must give 
*** j the command: 

CALL SWPMWESX 

; To write enable the monitor. After you have made 
; your changes you must give the command: 

CALL SWPMWPSX 

; to write protect the monitor again. 

HDDT may also be entered from process level via JSYS: 

JSYS 777SX 

or 
MDDT%SX ; will enter MDDT from the context of the current process 

If you wish to examine the system from the EXECs inferior for* 
anitor context: 

$ENA 

SSDDT 

DDT 

JSYS 777SX 
w MDDT 

> return to user context: 

MRETN$G 

;e SETMPG to map pages to this context: 

page 677 has been traditionally used for this? 

but any unused page may be used. To make sure that the page 

is currently unused type: 

ADDRESS/ ? i the guestion mark from DDT indicates that the 

; page is nonexistent, 

when the destination page has been found, set up AC2 as: 

AC2/ ACCESS,, 677000 

If the page has its own SPT slot: 

AC1/SPT INDEX 

the source page does not have its own SPT slot, it will belong to 
.ther a file or process page table. It will be represented as an 
>d* v into this page table: 

AC!/ SPT INDEX OF PAGE TABLE,, INDEX INTO PAGE TABLE 

9-Sep-80 
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Access = read or/and or write access 
Read/Write access ». 140000 In LH 

Therefore, to map a page, call with either* 

AC1/SPT INDEX OF PAGE 
AC2/140000,, 677000 

or 

AC1/SPT INDEX OF PAGETABLE, , INDEX INTO PAGE TABLE 
AC2/140000,, 677000 

AND SAY; 

CALL SETMPGSX 

The page will then be mapped to page 677. In examining locations 
677000-677777, you will be looking at the contents of the page. 

If you desire to map another page into this slot, merely call SETMPG 
again with arguments for the new page. You need not first un-map the 
old page. However, when you are finished, page 677 should be 
un-mapped in the following manner: 

AC1/0 

AC2/ACCESS,, 677000 
CALL SETMPGSX 

WARNING: 

Calling SETHPG incorrectly can crash the system. Be CAREFUL* Do not 
use SETMPG on a time sharing system if a crash will cause bad 
feelings. 

9-Sep-80 
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NOTE 

Not to be confused with "EEDDT command 
to get into UDDT used with the command 
processor* 



To get into EDDT you must bring the system up using the 
witch-register. See the DECSYSTEM-20 Operators Guide for a 
iscussion of switches. Go through the KLINIT dialog and when you get 
he prompt BOOT>, respond with: 

BOOT>/L 
BOOT>/G141 

he VL" command causes the monitor to be loaded, but not started, 
he "/G14i M starts the monitor at location 141, which is a jump to 
DDT, You can use EDDT like UDDT under timesharing on the MONITR,EXE 
ile by giving the following commands: 

w SGET <SYSTEM>M0NITR,EXE 
SSTART 140 

DDT is linked into the monitor and is always there. You may also get 
o EDDT from MDDT by issuing the following: 

EDDTSG 

rom MDDT, This stops timesharing. To resume timesharing and /or get 
ack to MDDT give the command: 

MDDTSG ; back to MDDT 

mretnsg ; back to normal timesharing 



Breakpoints may be inserted in the resident monitor with EDDT, 
jt not in the swappable monitor in general, because its pages may be 
•rapped out and be unavailable to EDDT, You can bring them in by 
fping: 

SKIP LOCSX ; where LOC is some address not in core 

9-Sep-80 
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There are some locations in the monitor that are very useful when 
using EDDT for debugging. They must be set before going on to start 
the monitor. 

They are i 

EDDTF 1 K«eP EDDT in core when system comes up 

delete DDT when system comes up (default) 

DBUGSW do not stop on BUGHLTs, crash and. reload 

1 stop on BUGHLTs (hit EDDT breakpoint) 

2 write enable swappable monitor, 

do not start up SYSJOB, and stop on 
BUGHLTs, Also it dosn't run CHECKD 
automatically on startup, 

DCHKSW do not stop on BUGCHKs (default) . 

1 stop on BUGCHKs (hit EDDT breakpoint) 

DINFSW do not stop on BUGINFs (default) 

1 stop on BUGINFs (hit EDDT breakpoint) 

In addition the symbol GOTSWM appears in the code just after the 

swappable monitor is loaded. So, if you want to debug the swappable 

part of the monitor you must put a breakpoint at GOTSWM (to get 
swappable part in core) by, 

GQTSWMSB 

Then start the MONITOR by, 

147SG 

CALL SWPMLKSX 

CALL SWPMLK is used to lock swappable monitor in core for debugging, 
You must have more than 96k of core to give this command since the 
resident and swappable monitor are larger than 96k, To start up. the 
monitor after you have gone into EDDT and set up your breakpoints 
(remember the last two are used for BUGHLT and BUGCHK) give the 
command j 

147SG 
or 

SYSG01SG 

If you are in EDDT and DBUGSW is not 2, that is the monitor is write 
protected, you can use the routines SWPMWE and SWPMWP to write enable 
and write protect the monitor, CALL SWPMWESX in DDT, 
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ILDDT Is distributed on the customer software tape, 

ie following is an chewed-up FILDDT,HLP file, 

STCFILE) FILE-SPEC 

>ads a file for DDT to examine, if you are looking at a monitor dump 
>u must load dump.cPY explicitly, FILDDT looks for MUMBLE.EXE not 
JMBLE.CPY that Is DUMP<ESC> will tell you that there is no such file 
r will load DUMP, EXE, When looking at a dump and you wish to load 
>e symbols you must first issue the load command followed by the get 
iramand. Be sure that the file from which you get the symbols is the 
irae version as the dump. Be sure, also that the monitor that was 
imped is the same monitor you use for symbols. That is don't get 
1NMED symbols to use with MONBCH etc, 

)AD (SYMBOLS FROM) FILE SPEC 

;ads specified file and builds internal symbol table, This must be 
le first command to FILDDT before "GET" wnen looking at a dump. You 
.11 most probably use <SYSTEM>M0NITR,EXE which would have been the 
mitor running at the time of the dump, 

IT (FROM FILDDT) 

turns to command level. You then may type a save command if a load 
mmand was just done to preload symbols. You will get a version of 
LDDT that has the symbols you just loaded in it so .you no longer 
ed to "LOAD" symbols. You now have a monitor specific FILDDT, which 
s common practice for TOPS-10, but is not generally done for 
PS-20, . 

LP 

pes something like this text, 

ABLE PATCHING 

lows writing on an existing file specified by a GET, 

ABLE DATA-FILE 

sumes file is raw binary (i,e, no ACs, and not an EXE file), 

T.iATURESs 

9-Sep-80 



Page 9- 12 
TOPS-20 Monitor Internals 

CRASH ANALYSIS 

EPSOU Sets monitor context for FILDDT mapping. EP Is a symbol 
which is equal to the page number of the eft, inex %j 

<CTRL/E> Returns to FILDDT command level, 
TRACKING DOWN UNMAPPED ADDRESSES 1 

The resident monitor may be looKed « *"hout any difficulties, 
but the swappable monitor may not be in core at the time of the dump. 
„\ h : value of the symbol is in the swappable monitor you must 
someUmeTgo ?hrSugh the monitor map to find where »• »<"U" "^ 
is. The location MONCOR contains the number of pages of w *J«;«J* 
««n4tnr and the location SWPCPO contains the first page of real core 
Tot swapping. So tf tSevalue of the symbol is greater than contents 
of MONCOR times iOOQ then it is in swappable monitor. 

If the page of the swappable monitor you want to look at is in «rj It 
«iii orobablv not be in core in the location that it's address refer 
JJ since ?he dump is of core and relocation of pages does not happen. 
£ fiSd where a symbol really is in the dump, f irst type the sy *ol 
followed by an •=". DDT will respond with, the value of this »*»&?*• 
The "live ot the symbol can be divided into two, three octal digit, 
fields. The high order three digits are the page number and the low 
order three digits are the offset into the page. 

If the value of the symbol is 324621 the high order three digits, 324, 
"., t. h . Daae number and the low order three digits, 621, are tne 
ott..t !nto the pm" 10 «»d the iocatlon of the page * n <" s „i m0 m J" 
the dump you Bust ioeK at the monitor map indexed by the page number. 
For examples 

MMAP+324/ 

would oive you the monitor map word for page 324. This word contains 
llll projection bits for the page and the address of the page when the 
dump was taken. 

The page may have been in core, on the swapping area or on the disfc at 
the time of the dump. 

If bits 14-17 in the monitor map word are non-zero the page 
was on the swapping area or dis< and is no longer available. 

Tf hits 14-17 are zero then the page was in core, and the right half 

of thl iota contains the page dumber in the dump of the page you are 

Jooklng fo? r cthe dump program overwrites the last several pages of 

memory, the dump therefore does not contain these last pages. 3 

If the page was in core the new address of the symbol you are poking 
for can be found by using the page number from the monitor "J* *°?J 
and appending the offset into the page to it. For example if MMAP+324 
conttilt lS4000,,256; then the new address of our symbol would be 
256621, 
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L^jddress In the swappable monitor must be resolved In this manner, 
n ^addition address of 600000 and above are in the JSB or PSB CPSB is 
age 777) and must be resolved by finding the page containing the JSB 
r PSB of the process that was running when the dump occured. There 
re some locations and tables in the monitor that make this easy: 



NAME 



FORKX 



INDEX DESCRIPTION 



none 



JOBNQ 


In PSB 


FKJOB 


Fork # 


JOBDIR 


Job t 


JOBPT 


Job * 


FKSTAT 


Fork # 


FKPGS 


Fork # 



Number of the fork that was running at the time of 

the dump, -1 if in the scheduler. 

Job number to which current fork belongs. 

Job numoer,,SPT index of JSB 

logged in directory number 

controlling TTY number*, top fork number 

test data,, address of fork wait routine 

SPT index of page table,, SPT index of PSB 



?T indexes are indexes into a share pointer table starting at SPT, 

3 find the PSB of fork 20, you first look at FKPGS+20 f If this 

scation contains 425,, 426, the word at SPT+426 is the pointer to the 

SB, This pointer can point to disk, swap area, or a page in the 
imp. If bits 14-17 are zero it is a pointer to a page in the dump 

id the right half of the SPT word is the page number of the PSB in 
■>e dump. 



vSn^you look 
:cured by lo 
lould check 
^formation 
I system. I 
JGHLT was is 
JGS.HAC to f 

)Int you ar 
>ok at the 1 
i in Appen 
I the call t 
»?", DDT 
in go to 
recipitating 



at a dump, you should first try to find why the dump 
oking at the location BUGHLT, If BUGHLT is zero then you 
the CTY log to find out why the dump was taken and for 
like the PC at the time of the dump and the status of the 
£ BUGHLT is non~zero it is the address of where the 
sued. You should look up the BUGHLT in BUGSTRING5.TXT or 
ind additional information about the BUGHLT, If at this 
e not sure as to why the BUGHLT occured, you will have to 
istings for more information, A copy of BUGSTRINGS.TXT 
dix A of the Operators manual. You can find the location 
o the BUGHLT by typing the BUGHLT tag to DDT followed by 
will tell which monitor module the BUGHLT is in and you 
your microfiche and read all about the conditions 

the BUGHLT, 



»xt if neces 
>s running; 
len the eras 
JGHLT, but 
sgisters are 
>od registe 
fSERR buffer 
sading and 
>rds contain 
le queued-up 



sary look at FORKX. I 
otherwise it is the 

h occurred. The regis 
if BUGACS+17 contai 
invalid and you must 

rs. This is done 
pointer, SEBQOU, the 
ACS, SEBDAT+BG%ACS. 

ing the users ACs, Yo 
SYSERR entry to get t 



f It contains a -1 the scheduler 
number of the fork that was running 
ters are saved at BUGACS on a 
ns something, ,BUGPDL+n, then the 
go to the SYSERR buffer to get the 
by adding to the right half of the 
offset into the buffer for the 
This value points to a 16 block of 
u may have to chain down more than 
o the BUGHLT block. 
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Do not forget to get a print out of the 
SYSERR log which will give you and the 
field service representative much of the 
information you can get out of the dump. 
The SYSERR output is much easier to 
examine, however,, clearly you cannot get 
as much info as you can from a dump. 

Some other locations in the PSB of interest are* 

LOCATION DESCRIPTION 

UAC User's ACs when he did his last JSYS. 

PAC monitors ACs 

PPC processors PC 

UPDL users pushdown stack while in a JSYS 

NSKED * oK to run scheduler 

>0 = cannot run scheduler 
INTDF -1 « ok to. receive software interrupts 

>s o , cannot receive software interrupts 

It may be useful to know the status of a fork when it is hung or you 
are unsure of its status. This can be determined by looking at FKSTAT 
indexed by the fork number. The right half of this location is the 
address of a test routine and the left half is data to be tested. For 
example if FKSTAT+12 contains 23,,FKWAT, then fork 12 Is waiting for 
fork 23 to complete, FKWAT is a routine that waits for another fork 
to complete and its data (the left half of the word) is the number of 
the fork it is waiting for. There are many different wait routines 
and you will have to look at the code to see what individual ones are 
waiting for. There Is a memo on scheduler tests which details most 
all of the scheduler tests in the monitor. 



You can easily determine all of the forks associated with a job 
by giving the commands] 

-i,,0$M 
FKJOB<FKJOB+NFKS>N, ,0$W 

Where N is the job you are looking for, A fork structure can usually 
be determined by looking at the FKSTAT of the forks and seeing which 
forks are waiting on which forks, A FKSTAT of FKSKP indicates a Cork 
is inactive. 

You should refer to STG.MAC for other fork and job tables and other 
locations in the PSB and JSB of interest. All of the above locations 
can be examined with mddt or EDDT while the monitor is running. Of 
course at these times you do not have to go through MMAP and the PSB 
and JSB that are in core are your own. 

There are two separate patch areas in the monitor (FFF and SWPF), FFF 
Is the resident patch area and SwPF Is the swapable patch area. These 
two symbols should be updated to point to the next free location in 
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IRASH ANALYSIS 

h^ j patch area when a patch is inserted, PAT., is defined to be 
qofl to SWPF, By convention, all distributed patches are applied at 
FF, This serves the purposes of reducing confusion, always working 
ntil the patch area is exhausted, and leaving patches always present 
n a dump for the cases where that is important, 

here are several general purpose routines that can be used to look at 
he the monitor while it is running. These routines should_be used 
ith caution since it is certainly possible to crash the monitor by 
sing them incorrectly. Two of the more general routines are MAPDIR, 
or mapping a directory into core, and SETMPG for mapping pages 
someone eises PSB or JSB) into core. You will have to look at the 
isting for the exact use of these and other general routines. Beware 
f the precautions that should be taken when using them. You can find 
he module they are located in by looking in the GLOB listing which is 
cross reference listing of all the global symbols in the monitor, 
ou get a GLOB listing in your microfiche, 
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BUGHLT, BUGCHK, BUGINF 



The monitor contains a considerable number of internal redundancy 
checks which generally serve to prevent unexpected hardware or 
software failures from cascading into severely destructive reactions. 
Also, by detecting failures early, they tend to expedite the 
correction of errors. 

There are two failure routines, 8UGCHK and BUGHLT for lesser and 
greater severity of failures. Calls to them with JSR are included in 
code by use of a macro which records the locations and a text string 
describing the failure. The general form is: 

BUG (TYPE, NAME, <STRING>) 
Where type is HLT or CHK, and string describes the cause. 
For example, 

BUG(HLT,SKDPFL,<PAGE FAULT FROM SCHEDULER CONTEXT>) 

The strings are constructed during loading and are dumped into a file. 
The BUGSTRINGS.TXT file will produce an ordered listing of the bug 
messages for operator or programmer use. 

BUGCHK is used where the inconsistency detected is probably not fatal 
to the system or to the job being run, or which can probably be 
corrected automatically. 

Typical is the sequence in MRETM in the SCHED module. 

AOSGE INTDF 

BUG(HLT,IDF0D2,<AT MRETN - INTDF OVERLY DECREMENTED>) 

This BUGCHK is included strictly as a debugging aid. Detection of a 
failure takes no corrective action. This situation usually results 
from executing one or more excessive OKINT operations (not balanced by 
a preceding NOINT), It is considered a problem because a NOINT 
executed when INTDF has been overly decremented will not inhibit 
interrupts and will not protect code changing sensitive data. 

BUGHLT is used where the failure detected is likely to preclude 

further proper operation of the system or file storage might be 

jeopardized by attempted further operation. For example, the 
following appears in the SCHED module: 

MOVE 1,T0DCLK ;CURRENT TIME 

CAML 1,CHKTIM ?TIME AT WHICH JOBO OVERDUE 

BUG(HLT,J0NRUN,<JOB NOT RUN FOR TOO LONG>) 

This check accomplishes two things: 
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i, A function of JOBO is to periodically update the disk 
version of bittabies, file directories and other 
files. Absence of this function would make the system 
vulnerable to considerable loss of information on a 
crash which loses core and swapping storage. JOB 
protects itself against various types of malfunction, 
this BUGHLT detects any failure resulting in a hangup, 

2. Detects if the entire system has become hung due to 

failure of the swapping device or some such event, on 

the basis that if JOB isn't running, nobody's 
running. 



NOTE 



For Release 4, the program form the 
BUGxxx calls takes has been modified, 
and the new file BUGS. MAC contains 
hopefully useful information on each of 
the BUGxxx calls in one place. This 
should be considered a required 
debugging file. 



JUGSw: 

monitor cell, DBUGSW, controls the behavior of BUGHLT and BUGCHK 
len they are called, DBUGSW is set according to whether the system 
! attended by system programmers, 

I CCDBUG5w)=o, the system is not attended by system programmers, so 
LI automatic crash handling is invoked. BUGCHK will return +i 
nmediately, appearing effectively as NOP. BUGHLT will, if called 
:om the scheduler or at PI level, invoke a total reload from the disk 
id a restart of the system. The BUGCHK/INF output will appear on the 
?Y and in the SYSERR log when JOBO gets around to them, 

: the system continues to run or is restarted properly, the location 
the bug (saved over a reload) and its message will be reported on 
le CTY, 




stinction, 
"w CC DBUGSW) a 1 
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Operation Is the same as with except for breakpoint 
action, in particular the swappable monitor is write 
protected and SYSJOB is started at startup as 
described. 



CCDBUGSW) s 2 



Is used for actual system debugging, the swappable 
monitor Is not write protected so it may conveniently 
be patched or breakpointed, and the SYSJOB operation 
is not started to save time, 

BUGCHK and BUGHLT procedures are the same as for 1. 



The following is a summary of DBUGSW settings: 



MEANING 

BUGCHK action 
BUGHLT action 
SWPMON write protect? 
CHECKD on startup 



Unattended 

NOP 

Crash System 

Yes 

Yes 



Attended 

Hit Breakpoint 
Hit Breakpoint 
Yes 
Yes 



Debugging 

Hit Breakpoint 
Hit Breakpoint 
No 
No 



Other console functions: 

In addition to EDDT, several other entry points are defined as 
absolute addresses. The machine may be started at these as 
appropriate, 

; go to EDDT 

; reset and go to EDDT 

; copy of EDDT address 

; initialize file system 

; restart 

1 reload and start 

; start 

The soft restart (address 145, EVRST) restarts all I/O devices, but 
leaves the system tables intact. If it is successful, all jobs and 
all Cor all but 1) process will continue in their previous state 
without interruption. This may be used if an I/O device nas; 
malfunctioned and not recovered properly. The total restart 
initializes core, swapping storage and all monitor tables, 
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140 


JRST 


EDDT 


141 


JRST 


SYSDDT 


142 


JRST 


EDDT 


143 


JRST 


SYSLOD 


144 







145 


JRST 


SYSRST 


146 


JRST 


SYSGOX 


147 


JRST 


SYSGOl 
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:rash analysis 

^ - jy limited set of control functions for debugging purposes has 
jeW built into the scheduler* Xo invoke a function, the appropriate 
>it or bits are set into location 20 via MDDT, The word is scanned 
:rom left to right CJFFO), The first 1 bit found will select the 
function* 



>IT 0; 



iit i: 



IT 2: 



Causes scheduler to dismiss current process if any and stall 
(execute a JRST ,), with -i in ACO. Useful to effect a clean 
manual transfer to EDDT, System may be resumed at SCHEDO, 

Causes the job specified by data switch bits 18-35 to be run 
exclusively. Temporarily defeats JOB not run BUGHLT, 

Forces running of JOB backup function before halting the 
system. 
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BUG'TYP MACRO CHANGES FOR VERSION 4 OF TOPS-20 

Version 4 of TOPS-20 will include some changes in the BUG code 
Generation. The purpose of these changes is to generate a document 
describing the TOPS-20 BUGCHKs, BUGHLTs, and BUGINFs that are more 
descriptive than the previous BUGSTRINGS.TXT file. 

The logistics of this change include moving the BUG definitions out of 
the monitor source listings and into a central source file, This 
source file will serve both as the definition file for the bugs ancl as 
doc-umtntaJion tor the BUGS, This file is ""e^ 8 ^ 3 ^/^ "l 11 ^ 
distributed to all sites on the distribution tape. These BUGS are 
still referenced in the source module where the bug Is invoiced but 
they are defined in BUG5.MAC. 

This involves a modification to the old BUG macro and * new w«o 
called DEFBUG, The BUG macro appears in the source modules and tn« 
DEFBUG macro appears in BUGS, MAC, 

The format of the new BUG macro is as follows* 



the new out» macro is as j.u**vwo. 

BUG (BUGNAM, <<xl,desi>,<x2,des2>, . •>) 

j_ *i_~ ...... 4 +>« «. KAfla uhar» l"h*» BUG C8 



This is placed in the monitor code where the BUG called BUGNAM is to 
occur; This macro executes a macro with name 'BUGNAM' which generates 
a XCT BUgRaS Inert the contents of BUGNAM is a JSR BUG'TYP. following 
the location BUGNAM are the Accumulators to be printed (one AC per 
word) followed by SIXBIT/BUGNAM/, The Accumulators to be Prated are 
defined with the DEFBUG macro while the locations specified in the BUG 
macro are for documentation only, 

AccomDanvina this BUG macro is a DEFBUG macro which is placed in the 
All P |uG5?Sac. This entry completely defines the BUG, including its 
type (BUGHLT, BUGCHK, or BUGINF) and documentation. 

The format of the DEFBUG macro 1st 

DEFBUG (TYP, TAG, MOD, WORD, STR,LOCS, HELP) 

For a description of the arguments to this macro see the SWSKIT 
article called BUGS.MEM. 

in order to make listings (output from MACRO or CREF) more informative 
than before, the BUG macro will cause the statement of the short 
description displayed in the listing where the BUG macro is called, 
till, the flavor of bug (INF, CHK, or HLT) and whether it's hardware 
or software related will be displayed in the listing. Hence the 
OVRDTA bug would appear in the listing as 
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.,. BUGCOVRDTA) 

*** ;BUG Type: hardware-related BUGINF 

;BUG description: PHYSIO - OVERDUE TRANSFER ABORTED 

When fully documented, the BUGS. MAC file will be extremely useful 
or specialists. It will describe, in one convenient place, what the 
dditional data printed on the console is, what caused the bug, and 
hat the site or specialist should do if that particular bug occurs. 

ere is a section of the current BUG definition/documentation for the 
UG GIVTMR from BUGS. MAC: 

EFBUGCINF, GIVTMR, JSYSA, SOFT, <GIV0K TIMEOUT>,«T2,FUNC»,< 

ause: The access control job has not responded with a GIVOK within 
the designated time period. 

ction: If this consistently happens with the same function code, you 
should see if the processing of the function can be made 
faster. 

If there is no obvious function code pattern, you may need to 
Increase the timeout period or rework; the way In which the 
access control program operates, 

at^ FUNC - the GETOK function code 

>) 

MF specifies the bug is a BUGINF. GIVTMR is the name of the bug, 
5YSA Is the module that the bug would occur In. SOFT specifies that 
t is likely the bug is caused by a software bug, <GIVOK TIMEOUT> is 
ie bug string. <T2,FUNC> specifies the data that will be printed on 
■»e operator's console. The initial spec called for the descriptor 
JNC to be included in the operator's message but at this time, this 
tscriptor is just for source documentation, 

ve blurbs following the initial line of the BUG definition attempt to 
►scribe to the specialist, in a more detailed manner than the 
sscription printed on the console, what it means when this bug occurs 
id what should be done first in order to resolve the situation. In 
>is case the ACTION is to examine the GETOK routine which is executed 
>r the additional data FUNC, This routine is getting hung up, 
>metimes, the ACTION will state to call the hot line or to submit an 
>R. These descriptions will help the specialist be more informed 
>out the bugs which may occur at one of their sites and save them the 
.me of calling the hot line or searching through the source module 
>r an idea of the problem. 
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TOPS-20 SCHEDULER TEST ROUTINES 



The fol 
tests used 
This include 
monitor tabi 
and left the 
FKSTAT tabl 
test routine 
unblocked. 
A nonskip re 



lowing is a tabulation 
by the TOPS-20 monitor 
s ARPA and DECNET test 
e FKSTAT indexed by fo 

GOLST (i.e. LHCFKPT) 
e words is TEST DATA 
s are called periodica 

This is indicated by 
turn is talcen if the p 



of (hopefully) all of the scheduler 
, time-frame approximately Release 3A, 
s. This Is the data one finds in the 
rk number for forks which have blocked 

contains WTLST) . The format of the 
,,TEST ROUTINE ADDRESS, The scheduler 
lly to determinie If a process can be 
a skip return from the scheduler test, 
rocess cannot yet be unblocked, 



When examining the monitor because of a hung job or fork, the 
FKSTAT table can often reveal the reason the fork is hung, and this 
sometimes even allows corrective action to be taken. 

The table below gives routine name, what you should expect to see 
in the FKSTAT table, and the module in which the scheduler test is 
defined, followed finally by a short description of what the particular 
condition is which is being tested. 



SCHEDULER TESTS 



TEST 
BALTST 
BATTST 

BLOCKM 



BLOCKT 



BLOCKW 
CDRBLK 



CONTENTS OF Tl AT TIME OF SCHEDULER CALL 



[CONNECTION #,, BALTST] 

Wait for network bit allocation. 



DEFINED 



CNETWRK] 



[UNIT #,,BATTST3 [DJjKALCI 

Wait for US.BLK, the lock bit for the BAT blocks 
on the unit, In the UDB to be zero, 

[TIME,, BLOCKM] tSCHED] 

Wait for TIME in BLOCKM format which is the low 
order 17 bits of the desired future time to be 
compared against a suitably masked todclk. 



[TIME,, BLOCKT] 
wait for TIME in BLOCKT format which is a 
value that Is shifted left 10 bits and compared 
against a suitably masked TODCLK, providing a 
longer delay than BLOCKM, but less precision, 

CTIME,,BL0CKW] B?r/ , eil , 

Wait for TIME in BLOCK*" format (same as BLOCKM), 



CSCHED] 



[SCHED1 



[UNIT NUMBER,, CDRBLK) CCDRSRVJ 

Wait for card-reader offline, or not waiting for 
a card, 
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:oftst 

)BWAIT 

>GLTST 

IGUIDL 

IGUTST 

USET 

ISGET 

I.«"T 

ISLT 

ISNT 
MPTST 

BKRT 

KRTST 

YQTST 



[ADDRESS,, CHKLQK3 CNSPSRV3 

Wait for NSP block lock at address to free, 

[TIME,,COFTST3 [MEXEC3 

Walt for job in FKJOBN to be attached or time 
in BLOCKT form to elapse, 

[DTE #,,DBWAIT3 [DTESRV3 

Wait for the TO-10 doorbell from the given DTE, 

[0,,DGLTST3 [DIAG3 

Walt for DIAGLK lock to be free, 

CUDB ADDRESS,, DGU1DL3 [DIAG3 

Wait for the unit to show as idle In the UDB, 

CUDB ADDRESS,, DGUTST3 [DIAG3 

Wait for the maintenance bit to set in the UDB, 

[ADDRESS,, DISET3 ESCHED3 

Wait for contents of ADDRESS to be zero, 

[ADDRESS ,,DISGET3 [SCHED3 

Wait for contents of ADDRESS to be positive, 

[ADDRESS,, DISGT3 CSCHED3 

Wait for contents of ADDRESS to be greater than 
zero, 

[ADDRESS,, DISLT3 CSCHEDJ 

Wait for contents of address to be less than 

zero. 

[ADDRESS,, DISNT3 CSCHED3 

Wait for contents of ADDRESS to be non-zero, 

[COUNT,, DMPTST3 [103 

Wait for count to be less than DMPCNT to indicate 
dump mode buffers freed, 

[PAGE #,,DSKRT3 . CPAGEM3 

Wait for CSTAGE for PAGE * to not be PSRIP, 
meaning disk read completed, 

[PAGE #,,DWRTST3 [PAGEM3 

Wait for DRWBIT to clear in CST3CPAGE #), 
meaning write completed, 

[FORK #,,ENQTST3 CENQ3 

wait for the lock on ENFKtb+fork r, 

[ADDRESS OF FE UDB,,FE8WT3 CFESRV3 

Wait for EOF or input bytes available from FE, 
Wake also on invalid assignment. 
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FEDOBE 

FEFULL 

FORCTM 
FR2WT 
HALTT 
HI BERT 
HUPTST 

IDVTST 
IMPBPT 

JBOTST 

JRET 

JSKP 

JTQWT 

LCKTSS 

LKDSPT 



[ADDRESS OF FE UDB,,FEDQBE3 

Wait for output buffer empty and all bytes are 
acknowledged by the FE, Wake also if not a 
valid assignment. 

[ADDRESS OF FE UDB, ,FEFULL3 

Wait for the current count of output bytes to be 
less than the count of bytes in the interrupt 
buffer, wake also on invalid assignment, 

CSUPERIOR FORK INDEX,, FORCTM] 

Identifiable wait forever, forced termination, 

[PREVIOUS TEST,,FRZWT3 

Identifiable wait forever, frozen fork, 

CSUPERIOR FORK INDEX, , HALTT] 

Identifiable wait forever for halted fork. 

[TIME,,HIBERT3 

Wait for TIME in BLOCKT format, 

[<0:9>TIME<10J17>HOST #,,HUPTST3 

Wait for IMPHRT bit set for host or time out In 

BLOCKW form, 

CO,, IDVTST] 

Wait for the lock on IDVLCK to free, lock it, 

CO IMPBPT] 

Wait for IMPFLG nonzero, or IBPTIM timer to run 
out, or IDVLCK lock free and output scan needed 
for the IMP, 

[TIME,, JBOTST] 

Wait for JBOFLG set nonzero for explicit request 

or time in BLOCKT form to elapse, 

[0,, JRET] 

wait forever, interruptible, 

CO,, JSKP] ,.,,.., 

Unconditional skip used to schedule immediately, 

CO,, JTQWT] 

Wait for JSYS trap queue, 

[ADDRESS,, LCKTSS] 

Wait for lock at ADDRESS to unlock, lock it, 

CO,, LKDSPT] 

Wait for room in LDTAB table of directories 

currently locked. 



[FESRVl 

CFESRV3 

CSCHED3 

[FORK] 

[SCHED] 

CSCHED] 

[NETWRK3 

CIHPDV] 

[IMPDV3 



[MEXEC] 

CSCHED] 

CSCHED] 

[SCHED] 

[10] 

[STG3 
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iKI ST 



iQDWAT 



PTDIS 



TARWT 
TAWAT 
IDWT1 

:pukt 

[CTST 

DTTST 
5PTST 

fTNTT 
>NLKT 

;dwat 
ib^t 



EINDEX INTO LDTAB,,LKDTST3 ESTG3 

Wait for bit in LCKDBT to clear, indicating 
directory unlocked, 

[ADDRESS OF STATUS WORD, ,L0DWAT3 ELINEPR3 

Wait for flag LP%LHC to set in the addressed 
word, indicating loading has completed of the 
VFU or RAM file, 

EUNIT ADDRESS,, LPTDIS3 [LINEPR] 

Wait for an error condition on the addressed 
unit, or for all buffers cleared and no bytes 
still in the front-end, before finishing close 
operation on the device, 

ElORB ADDRESS,, MTARWTJ [MAGTAP3 

Wait for IRBFA in the IORB to Indicate that this 
IORB is no longer active, 

[UNIT #,,MTAWAT] CMAGTAP3 

Wait for all outstanding lORBs for unit to be 
finished, 

CUNIT #,,MTDWT1] CMAGTAP3 

Wait for the count of outstanding requests on the 
unit to go to one, 

E0,,NCPLKT3 [NETWRK3 

Wait for locK NCPLCK to free, lock It, 

E0,,NICTST3 CPAGEM3 

Wait for SUMNR less than or equal to MAXNR or 
only one fork: in 8ALSET. 

E<0«8>CONNECTION #<9U7>STATE, , NOTTST3 [NETWRK3 

Walt for connection to leave state, 

C0,,NSPTST3 CNSPSRV3 

Wait for KDPFLG nonzero, indicating KMCli wants 
service, or HSGQ nonzero, indicating messages to 
process, 

E<0j8>OPTION #,<9:17>LINE #,,NVTNTT3 ETTNTDV3 

Wait for completed NVT negotiation, 

EOFN,,OFNLKT3 EPAGEM3 

Wait for OFN unlocked— SPTLKB zero in SPTH(OFN), 

EFORK #,,PIDWAT3 ETPCF3 

Wait for bit for fork in PDFKTB to set, 

E0,,SEBTST3 [SYSERR3 

Wait for SECHKF to go nonzero before starting 
Job task to write queued SYSERR entries. 
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SEEALL 



SPCTST 



"1ST 



•ST 



'ST 



AT 



AT 



KT 



:t 



IT 



- < 



TCOTST 



TRMTS1 



CO,, SEEALL] ,■ , t . .. 

Waits for SNDALL to go to zero, indicating the 
send-all buffer available, 

to,, SPCTST] 
Wait for a node, 

CO SPMTST] 

Wait for page in SPMTPG to be on SPMQ or the 

time SPMTIM to expire, 

CO,,SQLTST] 

Wait for the special queues locK 50LCK and lock 

it. 

[SDB ADDRESS OF STRUCTURE, ,STRTST] 
Wait for the structure lock to be free, 

tADDRESS OF STATUS WORD, ,STSWAT] 

Wait for flag CD%SHA to come on in the addressed 

word, indicating that cardreader status has 

arrived, 

[ADDRESS OF STATUS WORD, ,STSWAT] 

Wait for flag LP%SHA to set in the addressed 

word, indicating that printer status has 

arrived, 

[FORK #,,SUSFKT] 

Wait for for* to be on WTLST in either SUSWT 

OR FRZWT, 

[PAGE #,,SWPRTJ «--,« 

Wait for CSTAGE for PAGE I to not be PSRIP, 
meaning swap read completed, 

10 SWPWTT] 

Wait for NRPLO nonzero, Increment CGFLG each 

time test is unsuccessful, 

[FORK #,,TCIPIT] 

Waits for no interrupts pending for FORK #, 

[LINE f,,TCITST] 

wait for line inactive, no fork in Input wait, 

or input buffer non-empty, 

[LINE #,, TC0TST3 

Wait for line Inactive, or output buffer not 

too full to add a character to it, 

tO,,TRMTSi] ■,*„.., 
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!Ri_ST 



!RP0CT 



'SACT1 

SACT2 

SACT3 
STSAL 

TBUFW 
TIBET 
TOAV 

TOBET 
DITST 
DWDON 
PBGT 

SGWAT 
VBWAT 
ATTST 



CFORK #,,TRMTST3 

Wait for FORK • to be on WTLST for either HALTT 

or FORCTH, 

[MINIMUM NRPLQ,,TRPOCTJ 

Wait for NRLPQ to be above stated minimum or 
normal minimum. Increment CGFLG each time 
test is unsuccessful, 

[LINE #,,TSACT13. 

Wait until line inactive, becoming active, or 

has a full length dynamic block assigned, 

[LINE #,,TSACT23 

Wait for line available—Inactive or fully 

active. 

[LINE #,,TSACT33 

wait for line inactive— dynamic data unlocked, 

[0,,TSTSAL3 

wait for SALCNT to go to zero, Indicating the 

send-all is finished for this buffer, 

[NUMBER,, TTBUFWJ 

Wait for NUMBER of buffers, 

[LINE #,,TTIBET3 

Wait for line inactive or input buffer empty, 

[LINE #,,TT0AV3 

Wait for line Inactive and output buffer not 

empty, 

[LINE #,,TT0BET3 

Wait for line Inactive or output buffer empty, 

[0,,UDITST3 

Wait for at least two free IORBs on UIOLST, 

[IORB ADDRESS,, UDWD0N3 

Wait for IS, DON to set In IRBSTS for this IORB, 

[CONNECTION INDEX, ,UPBGT3 

Wait for LTDF connection done flag to set, or 

output buffers to appear, 

[0,,USGWAT3 

Wait for lock on queued USAGE blocks to free, 

[UNIT *,,VVBWAT3 

Walt for the MDA to reset TPVV handling EQV, 



[<0:8>CQNNECTION #<9| 17>STATE, , WATTST3 



9" 



[FORK3 
[PAGEM3 

[TTYSRV3 

CTTYSRV3 

[TTYSRV3 
[TTYSRV3 

CTTYSRV3 
[TTYSRV3 
[TTYSRV3 

[TTYSRV3 
[PHYSI03 
CPHYSI03 
[IMPDVJ 

CJSYSAJ 

[TAPE] 

(NETWRK3 
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Wait for connection to be in state, 

HtrKT CFORK #,,WTFKTJ WORM 

Wait for forte to be on WTLST, 

WTSPTT tPAGE #,,WTSPTT3 tSCHEDJ 

Wait for share count on PAGE # to go to 1. 
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MAPPING DIRECTORIES IN MDDT 



Release 3 of TQPS-20 can take advantage of the extended 
iddresslng features of the model B processor. Some of Its data has 
>een reorganized and moved into non-zero sections of the addressing 
pace. One of the things moved was directories. Directories are now 
lapped into section 2, starting at the beginning of the section. Thus 
he old procedure of reading a user's directory in MDDT is no longer 
alld. This will describe how to map a directory correctly, for 
elease 2 and for releases 3, 3A, and 4, 

The procedure for release 2 was the following. You first have to 
:ind out the structure number and directory number for the directory 
o be mapped. You can, use the TRANSL program to get the directory 
umber, or use the "EPRINT command to list the directory information, 
s an example, suppose you want to find the directory and structure 
nformatlon for the directory SNARK: <DBELL>, You run TRANSL and 
btain the results! 

TRANSL SNARK;<CURDS> 
N^KCURDS> CIS) SNARK: C4,117J 

he "programmer number" obtained is the directory number, in octal, 
n this example, the directory number is 117, if the directory is in 
ad shape, and you can't run TRANSL or use "EPR1NT, you will have to 
ind out the directory number by looking at the output from a DLUSER 
r ULIST run, or from BUGCHK output. 

To find the structure number, you have to work harder. If the 
tructure is mounted as PSs, its structure number. is always 0, . For 
tructures mounted other than PS*, you do the following. You get into 
DDT, and look at the table STRTAB, This table contains all of the 
ddresses of the structure data blocks in the system. The first word 
f each structure data block is the structure name in SIXBIT. So. you 
earch the tables looking for the desired structure. The offset into 
he table STRTAB is then the structure number. For our examples 



ENABLE 








SDDT 








DT 








SYS 777SX 








DDT 








S6T 








TRTAB/ ,8C 


/ 


PS 




TRTAB+1/ 


M-I 


/ 


REL3 


TRTAB+2/ 


M.% 


/ 


SNARK 



n the example above, you see that PSi Is the first structure, 
ollowed by the structures REL3? and SNARKs, since the offset into 
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STRTAB was 2 for SNARK3, the structure number you want Is 2. 

Knowing the structure number and the directory number,, you can 
now map the directory and look at it. When the directory is mapped, 
location DIRORA will point to the area in the monitor you can find it 
at. This is currently the address 740000, To save typing, you can 
use the symbol DA, which has the value 740000 (none of the examples 
here uses this symbol however). To map the directory, you call the 
routine MAPDIR which is in the module DIRECT, It takes two arguments. 
The directory number goes in ACl, and the structure number goes in 
AC2, For our example, the output looks likei 

DIRORAI 740000 
740000/ ? 

U 117 

2! 2 

CALL MAPDIRSX 

S$ 

740000C 400300, ,100 

The skip return from MAPDIR means you have successfully mapped the 
directory. You can now look at the whole directory by examining the 
proper locations. The number of pages that are mapped by MAPDIR is 
30, which is the length of a directory, so the whole thing is 
available to look at. By examining or changing location 740000+N in 
core, you are examining or changing location N of the directory. When 
you are finished, you can Just leave' MDDT by jumping to MRETN or by 
typing *C, 

In release 3, however, when you examine location DIRORA after 
calling MAPDIR, it doesn't have to contain 740000. If it does, then 
your machine cannot support extended addressing and the monitor is 
running the same as release 2 did. In this case you can ignore the 
rest of this document. If your machine does have extended addressing, 
when you examine location DIRORA you will see the number 2,,0. This 
address is now in section 2 of the monitor, and MDDT cannot read the 
data there directly. If you look at the location 740000 after calling 
MAPDIR, it will still be unreadable, since the directory is no longer 
read In there. Those pages are now unused,. 

To be able to read the directory now, you have to tell the 
monitor to map in the pages where you can see them with mddt. The 
first step Is to examine the location DRMAP. This location is the 
section pointer for section 2, where the directories are mapped. This 
is a share-type pointer, which contains the 0FN for the desired 
directory in the right half. This number is one of the arguments for 
the MSETHP routine, MSETMP takes the following arguments, ACl 
contains the 0FN in the left half, and the first page number to be 
mapped in the right half, AC2 contains flag bits in the left half, 
and the address where you want to map the pages in the right half, 
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\<5W' contains the number of pages to be mapped. For mapping 
iirectories, you can use 740000 as the address, and you want to map 30 
sages. You also want to set flag bits so that the directory can be 
rhanged. For the example, you do the following: 

)RMAP[ 224000,, 147 

LI 147,, 

!i 140000, ,740000 

II 30 

:all hsetmpsx 
\ 

kfter the call to msetmp, the directory is now mapped in 740000, and 
'ou can proceed as you used to in release 2. When you are finished 
rlth the directory, you should call MSETMp again to unmap the 
lirectory. This is done by supplying the same arguments as before, 
sxcept that ac 1 contains zero. As an example! 



J 
!l 140000, ,740000 

II 30 

:all msetmpsx 



ow'you can simply *C out of MDDT or jump to MRETN, 



For Release 4 of TOPS-20, the various flavors of DDT have been 
:rained to understand extended addresses, so the mapping contortions 
ised for 3 and 3A are once again unnecessary. On extended machines 
me can reference section two directly as below? 

IRORAC 2,,0 

,,0t 400300, ,100 

hen done, you can still just *C out or jump to MRETN, 

9-Sep-80 



TOPS-20 Monitor Internals P«9e 9-32 

JSB AND PSB MAPPING 

An Easy Way to Examine the PSB and JSB of Another Job 



There is an occasional need to look at the state in detail of 
another Job on the system. A common reason for doing this is to find 
the cause and cure of a "hung job" which cannot be logged out. To 
find out what the job is doing you usually start by looking at the 
JST5 stack in the PSB, But you cannot examine such data easily 
because the fork data in the PSB and the job data in the JSB are not 
in the monitor's address space until the fork is run. If you try to 
look at the PSB or JSB using MOOT you will see the data for your own 
forK, To look at the data for another fork you must do what the 
monitor does, and that is to map it. 

A procedure for doing the mapping of a PSB or JSB was given in 
the released and 3a SWSKITs. You first find the SPT index of the PSB 
or JSB you want to map, then you call setmpg or M5ETMP to set up 
pointers to the data, and then you can examine it. But there are 
several problems in using that method, which are: 

1. You have to find an empty set of pages in the monitor's 
address space which can be used for mapping. 

2. There is not enough room to map all of the PSB and JSB, So 
if you want to examine many different things you have to do 
the mapping many times, 

3. The routines SETMPG and HSETMP do no validity checking of 
their ' arguments. Thus if you feed them bad data the system 
will probably crash. So If you need to map things many times 
your chances are you will make a mistake once too often, 

4. The addresses of the data are not correct. To look at PPC 
for example, you can't just examine location PPC (which would 
be for your own fork). You have to look in the page you are 
using for mapping. So every reference has to be offset by 
some constant. 

5. When you are done looking at the fork, you can't simply leave 
MDDT, You have to call SETMPG or MSETMP again to -unmap the 
data, 
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'^ since that documentation was written I have found a procedure 
rhich is much easier. It eliminates almost all of the above problems. 
!he procedure is this: 

1, Do a "GET" of the file the monitor was loaded from, usually 
systemsmonitr.exe, 

2, Enter user mode DDT in the file you got, and then do a JSYS 
777 to get into MDDT, 

3, Find out the SPT Indexes as before, and call MSETMP to map 
the PSB or JSB to the USER address space, in the correct 
Place!! 

4, Return from MDDT, and examine PSB and JSB locations directly, 
and see the correct data in the right place, 

5 C When you are done, just *C and do a RESET, 



The rest of this document will document step by step how the 

rocedure above is done, by using an example. Assume that we wish to 

xamine the state of for* 105, which belongs to Job 2i, We then 

et^^i 
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9ENABLE 

SGET PSKS*STEM>MQNITR.EXE 

SSTART 140 

DDT 

JSYS 777$X 
MDDT 



JGet a copy of the monitor 
lGet Into user DOT 

lEnter MDDT 



iFollowing Is an example of the procedure to map the JSB of a jobt 



FKJOB+105C 25, ,2035 



Til 
T2I 
T3i 



2035,, 

540000,, JSBPGA 

JSLSTA'IOOO-JSBPGA'IOOO 



CALL MSETMP$X 
$ 



JGet the SPT index of the JSB 
tof fork 105 

IPut SPT index in left half 
I* Flags and where to map to 
INuraber of pages to map 

IDo the mapping 



IFollowing is an example of the procedure to map the PSB of a fortes 



FKPGS+10SC 2657, ,2332 



Til 

T21 
T3i 



2332, ,PSBMAP-PSBPGA 

540000,, PSSPSA 
PSBMSZ 



CALL MSETMPSX 

$ 



IGet the SPT index of the PSB 
iof fork 105 

IPut SPT index in left half, 
land offset in right half 
I* Flags and where to map to 
INumber of pages to map 

IDo the mapping 
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E^^flpXe of returning to user mode and looking at data from both 
the PSB and the JSB of the fork: 



RETNSG 



iReturn to user mode 



SRNAME 3 

SRNAM+it 422050, ,546230 $T;DBELL 

TRLTTC 777777, ,777777 

ILBYT+MLJFNt 4400,, 334010 

PC/ Tl,,DI5XE#+2 

AC+17/ -215,,UPDL+62 

PDL/ CHKH05* 
PDL+i/ CAM CHKAE0#+12 
PDL+2/ CHKH05* 
PDL+3/ CAM CHKAE0#+12 
PDL+4/ Tl,,,COMND+l 
PDL+5/ -273,,UpDL+4 



{Examine job's user name 

{Controlling terminal 
{Start of data block for JFN l 
{Current PC of the fork 
{Current stack pointer 
{First few stack locations 



ESi^ple of terminating the mapping we have done: 



C 
RESET 



{To finish, just quit and reset 



The procedure as given above maps the JSB and PSB write-enabled. 
a if you find something you want to change, you can simply deposit 
ie new value into the location. If you want the data to be 
rite-protected, then change the 540000 to 500000 in the two steps 
srked with an asterisk. 



Warning: The procedure of mapping things into your user address 
sace has its limitations. Mapping the JSB and PSB works because the 
ser core used for mapping was previously empty. In general, you can 
Uy map things into your user core if your core pages are either 
snexistant or are private. If you call MSETMP or SETMPG and map 
jmethlng over a shared page, the old file page is unmapped without 
ie share counts being updated, which prevents your job from logging 
it later. To get around this problem you can BLT your core image to 
>r all of the pages to be private, 
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HOW TO USE BREAKPOINTS IN CODE THAT MANY USERS EXECUTE 



When inserting a breakpoint into the running monitor, you have to 
be careful that no other users will execute the code containing the 
breakpoint. If some other user hits the breakpoint, they will blow up 
with an illegal instruction since MDDT will not be there to handle the 
breakpoint. This normally limits the places you can set breakpoints, 
since most of the monitor can be gotten to by any user. Even if you 
run the system stand-alone, it is possible that the routine you are 
debugging will be called by job 0. However, it is still possible to 
do such debugging, even on a system which is not stand-alone, and this 
document will describe how this is done. 

The essential element of this technique is to put in the patch in 
such a way that only your own fork can ever reach the breakpoint. 
First you write a simple routine which will skip if it is not being 
run by your particular fork. This can be done easily if you remember 
that the location FORKX contains the currently running fork number, 
An example of such a routine is the following: 

©ENABLE 

SSDDT 

DDT 

JSYS 777SX 

MDDT 

FORKXC 23 f check our fork number 

FFF/ NOTME: PUSH P,T1 1 save an AC 

NOTME+1/ MOVE Tl, FORKX ; get currently running fork number 

NOTME+2/ CAIE Tl,23 / is it us=23? 

NOTME+3/ AOS -HP) ; no, setup skip return 

NOTME+4/ POP P,T1 / restore the saved AC 

NOTME+5/ POPJ P, ; and return to caller 

NOTME+6/ FFFt ; reset the position of FFF 

The routine above simply saves AC Tl, gets the currently running fork 
number, compares it with your own fork number which you obtained by 
looking at location FORKX, and skips if they differ, 
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Now assume that you want to set a breakpoint into the 
ode, which is in the routine BLKSCN in the module DIRECT, 

LKSC2/ HLRZ CBLKTABCB) 
LKSC2+1/ CAME A,C 
LKSC2+2/ AOBJN B,BLKSC2 
LKSC2+3/ JUMPGE B,BLKSCE 
L.KSC2+4/ HRRZ B,BI*KTABCB) 



following 



ssume you 
allowing: 



want the breakpoint at location BLKSC2+3, You do the 



PFF$< ; patch this location 

; call the notme routine 

; me if it gets here, set breakpoint 



LKSC2+3/ JUMPGE B,BLKSCE 
FT/ PUSHJ P, NOTME 
?F+1/ ,$B JFCLS> 
FF+2/ JUMPGE B,BLKSCE 
FT+3/ JUMPA A,BLKSC2+4 
F-F+4/ JUMPA B,BLKSC2 + 5 
L.KSC2 + 3/ JUMPA NQTME+6 

atice that the breakpoint has been set in the JFCL instruction 
allowing the call to NOTME. Only your fork will execute it, so you 
an now debug the section of code while other users are executing it 
t ^p* same time. Remember to remove the breakpoint when you are 
>ne. 

To run a particular program while having breakpoints set, you 
ist remember that the breakpoint has to be set by the same process 
lich you expect to hit it. so for example, typing *EQUIT, setting a 
■eakpoint, returning to the EXEC and running your program will not 
>rk. You must enter MDDT and set the breakpoints from your program 
>u want to debug. As an example: 



:nable 

;et program 

>DT 

>T 

SYS 777SX 

>DT 



; get the program to be used 
; enter DDT 

; and enter MDDT from there 



'UT IN "NOTME" ROUTINE AND SET BREAKPOINTS HERE) 

LETN$G ; return to the context of the test program 

» ; start the test program 
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Using Address Break to Debug the Monitor 



Sometimes when examining a set of dumps, you will notice the crashes 
are caused by some location being destroyed, If you have no idea 
where the destruction is done from, finding the problem could be very 
difficult. One useful procedure in such cases is to use the address 
break feature of the hardware to track down the problem (except for 
2020'sl), The only problem is that the use of address break is not 
obvious. This Is a manual describing how to use address break in the 
TOPS-20 monitor. 



the 

must 

MDDT 

prope 

addre 

that 

occur 



In order to use address break, four things must be done. First, 
current routines the monitor uses to set address breaks for users 
be disabled, secondly, your own address break must be set from 
or EDDT, Thirdly, instructions which you want to execute 
rly have to be modified so that they will not cause an unwanted 
ss break, Finally, breakpoints must be placed in the monitor so 
the state of the monitor can be examined when the address break 
s. The following is a step by step example of doing this. 



Load the monitor for debugging, and enter EDDT. The procedure 
starting from BOOT is the following: 



BOOT>/L 

BOOT>/G140 

EDDT 

DBUGSW/ 

EDDTF/ 

GOTSWMSB 

SYSG01SG 



jLoad monitor but don't start it 
;Start EDDT 

/Set debugging mode 
;Keep EDDT once system starts 
Mnstall useful breakpoint 
;Start the monitor 



[PS MOUNTED] 
$1B»G0TSWM 



0$1B 



;Remove breakpoint now 



2, 



Disable the monitor's normal changing of the address break,, 
This Is currently done at two places: 



KISSAV+4/ DATAO UNPFG1+26 JFCL 
SETBRK+12/ DATAO A JFCL 



/Disable instruction 
;Here too 
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i. 



Set your own address break at the desired location. Refer to 
the Hardware Reference Manual for details. The instruction to 
set an address break is: 



DATAO APR,ADDR /Note: APR a 

where addr contains the following fields? 



Bits 

OTM4W 

9 

10 
11 
12 
13-35 



Description 

Break at given address on instruction fetches 

Break at given address on reads 

Break at given address on writes 

Oaexec address space, lsuser address space 

Address to break on. 



So now assume you want to catch a bug which is blasting 
location CURDS. You want to break only for writes, and want 
to use exec virtual space. Therefore you type the following: 



FFF/ 100000000+CURDS 
DATAO APR,FFF$X 



/Put data in convenient place 
/Set the address break 



Now you want to disable address break for all instructions 
which you expect to change the given location. Assume in this 
example that only location DIDDLE should change location 
CURDS, Then you do the following for a model B CPU: 



FFF J 

IT+lt 

IT+21 

IT+31 

IT+41 

IT+51 

IH-61 

IT+71 

IT+10J 



IT: 



IT+4 
EXCH IT 
TLO 1000 
EXCH IT 
JRST 5, IT 
FFF: 



/Define location to get old flags 

;oid PC 

;New flags 

/New PC 

;save AC and get old flags 

/set address break inhibit bit 

/Restore flags and AC 

/Return to caller 

/Redefine FFF 



diddle/ movem A, CURDS FFF$< /insert patch 

FFF/ o JRST 7,IT$> /Call above routine 

FFF+1/ MOVEM A, CURDS /Typed by DDT when finishing pater 

FFF+2/ JUMPA A,DIDDLE+1 

FFF+3/ JUMPA B,DIDDLE+2 

DIDDLE/ MOVEM A, CURDS JUMPA IT+10 

The JRST 7, IT instruction is used to save the old PC at IT and 
IT+1, and take a new PC from IT+2 and IT+3, There the old PC 
is changed to include the address break inhibit bit. Then a 
JRST 5, IT is done which returns to the caller. The next 
instruction then executes without causing an address break. 
You have to insert the JRST 7, IT instruction at every 



9-Sep-80 



TOPS-20 Monitor Internals 

USING ADDRESS BREAK TO DEBUG THE MONITOR 



Page 9-40 



instruction you want to succeed. 

For model A CPUs the procedure is similar, but a little easier* 



FFF1 

IT+ll 

IT+2J 

IT+31 

IT+41 

IT+51 



IT: 
EXCH IT 
TLO 1000 
EXCH IT 
JRSTF §IT 
FFFt 



/Define location to hold PC 

;Get old PC and save AC 

;Set address break inhibit flag 

; Restore PC and AC 

I Return to caller 

/Redefine FFF 



DIDDLE/ MOVEM A, CURDS FFFS< /Insert patch 

FFF/ JSR IT$> J Call above routine 

FFF+t/ MOVEM A, CURDS /Typed by DDT when finishing patch 

FFF+2/ JUMPA A,DIDDL£+1 

FFF+3/ JUMPA B,DIDDLE+2 

DIDDLE/ MOVEM A, CURDS JUMPA IT+5 



5. 



Now put the breakpoints into the monitor so that when an 
address break occurs, you will get into EDDT, There are two 
locations to patch, one for PI level and one for non-PI level. 
You also have to patch a monitor bug in release 3 and 3A so 
that the page fail dispatch code works properly. 



ADRCMPSB 
PFCD23SB 
PIPTRP+1/ 
9P 



MOVE A,TRAPSH 



/Set breakpoint at non-PI routine 
/Set breakpoint at PI routine 
MOVE A,TRAPS0 /And fix a bug 
/Now let the monitor proceed 



6. 



When either of the above breafcpoi 
of the instruction which caused 
locations TRAPFL and TRAPPC, I 
JSYS level (breakpoint was to 
zero) then an $P will proceed pro 
was from the scheduler or fr 
useless since the monitor will th 
want to see an address break unde 
this is ok If all you want to d 
causing the trashing. 



nts is hit, t 

the address 
f the address 
ADRCMP and lo 
perly. If th 
om PI level, 
en BUGHLT bee 
r these condi 
o is find 



he flags 
break wi 
break w 
cation I 
e addres 
doing $P 
ause it 
tions. 
the ins 



and PC 
11 be In 
as from 
NSKED IS 
s break 
will be 
doesn't 
However t > 
truction 



If the location still gets trashed after trying to catch it this 
way, either your procedure is wrong/ you are trying this on a 2020 
(which has no address break feature)/ the location Is being changed 
by some 10 being done (RH20s, DTEs, etc)/ or else the machine is 
having some hardware problems. 
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Sometimes after a monitor crash due to disk problems, some of the 
Irectories on the system will contain errors. These errors cause 
JGCHKs such as DIRFDB, NAMBAD, DIRPGO, and DIRPG1, It is sometimes 
assible to find the error in the directory by getting into MDDT, 
applng the directory, finding what is wrong, and fixing it. This 
rocedure is described in the 5WSKIT. However, this is not always 
asy, and may take a lot of time. It is therefore better in many 
ases to simply delete the bad directory and recreate It, This Is 
asy to do for most directories. But special procedures are necessary 
sr the directories <SYSTEM> and <SUBSY5>, The rest of this memo will 
ascribe the methods of recovering from bad directories, handling In 
articular the difficult case of the <SYSTEM> directory. 

You can first try to give the EXPUNGE command with the REBUILD 
id PURGE subcommands. If the problem with the directory is very 
Lmple, it may fix your problem. As an example, suppose the directory 
3;<SICK-DIRECTORY> is incorrect. You would type: 

SEXPUNGE (DIRECTORY) PS: <SICK-DIRECTORY>, 
$$REBUILD (SYMBOL TABLE) 
SSPURGE (NOT COMPLETELY CREATED FILES) 
$$ 
PS:<SICK-DIRECTORY> CNO PAGES FREED) 



If this does not help the problem, you will have to delete the 

:rectory and then recreate it. Before proceeding, you should make 

ire that any files you can reference are copied to another directory, 

else are saved on tape. Now first try to delete the directory 

trmally, as follows: 

SBUILD (USER) PS:<SICK-DIRECTORY> 

COLD) 

$$KILL 

[CONFIRM] 

$$ 

$ 
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If this Is successful then simply recreate the directory again, 
and restore the user's files. You should recreate the directory with 
the same directory number as it had before, so that DLUSER's data will 
still be correct* 

The procedure above will fail If either the directory is . mapped 
by another job, or if it is totally unusable. If it is mapped, and 
the directory Is a random user, you can wait until the directory is no 
longer in use, or you can take the system stand-alone so that no user 
can reference it. 

If the directory is totally unusable, you will then have to try 
to delete it the hard way. Before proceeding, you should try to 
delete and expunge all files In the directory. This will minimize the 
amount of lost pages that will result. Now there are two cases to 
consider. If the directory is not a sub-directory, you type the 
following: 

SDELETE (FILE) PS:<R0OT-DIRECT0RY>SICK-DIRECT0RY, DIRECTORY,, 
SSDIRECTORY (AND "FORGET" FILE SPACE) 

$$ 

<ROOT-DIRECTOR*Y>SICK-DIRECTORY. DIRECTORY, 1 COKJ 
S 



If the directory is a subdirectory, you modify the above command 
by replacing "ROOT-DIRECTORY" by the name of the next higher 
directory. Thus if the directory was PS:<ANOTHER.BAD-ONE>, you type: 

SDELETE (FILE) PS:<ANOTHER>BAD-ONE, DIRECTORY, 
SSDIRECTORY (AND "FORGET" FILE SPACE) 
SS 
<ANOTHER>BAD-ONE. DIRECTORY. 1 C0K3 

$ 



The above procedure tells the monitor to treat the directory file 
liJce a normal file, and to delete it as such. This means that any 
files in the directory will become "lost". The disk pages can be 
recovered later with CHECKD, If the above works, you simply can 
recreate the directory and restore the files. 

The only reason the above command should fail is if the directory 
is still mapped. For PS:<SUBSYS>, you can bring up the system 
stand-alone so that no programs are run from it, and then delete it« 
For PS:<SYSTEM>, even taking the system stand-alone will not help, for 
It is always mapped by job 0. But there are two procedures you can 
use which do work, 
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The safest method can be used If the user's system has mountable 
tructures. If you have built another PS? structure, you can mount 
he pack with the bad directory as an alias, and then the directory 
ill not be mapped and can be deleted, As an examples 

SSMOUNT (FILE STRUCTURE) SICK;, 

SSSTRUCTURE-ID CIS) PSS 

S$ 

WAITING FOR STRUCTURE SICK: TO BE PUT ON LINE,,, 

STRUCTURE SICKJ MOUNTED 

$ 

SDELETE (FILES) SICK »<ROOT«DXRECTORY>SYSTEM. DIRECTORY, 

SSDIRECTORY (AND "FORGET" FILE SPACE) 

$$ 

SICKs<ROOT-DIRECTORY>SYSTEM .DIRECTORY, 1 [OK J 
$ 



Then you can build the new directory, restore the files to it, 

id then use it again for your normal PSx pack. Be sure to build the 

»w directory with the same number. This is especially important for 
je special system directories. 

If you do not have another disk drive or another PS? disk, or If 
>u don't want to bother SMOUNTing the disk, you can fix the <SYSTEM> 
■ea by using MDDT. The basic idea is to patch the monitor so that it 
i longer thinks that the directory is in use. This is done as 
tllows: 

$*EQUIT 

INTERRUPT AT 17117 

MX>/MDDT 

CHKOFN/ JSP CXr.SAVE JRST RSKP 

MRETNSG 

$ 



Then you should have no problems deleting the directory, 
imediately after doing the delete, you should reload the system, 
ten the system restarts, you can read the monitor and the EXEC either 
om the distribution magtape or from another directory where you had 
pt copies. Then recreate the <SYSTEM> area, making sure to give it 
e same directory number as it had before. Then you can restore the 
le- and let the users Back on. Finally, you should run CHECKD 
mts_»,me to recover the lost pages. 
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Copyright CO 1978, 1979 
Digital Equipment Corporation, Maynard, Massachusetts, U.S. A, 

lis software is furnished under a license and may be used and copyed 
■>ly in accordance with the terms of such license and with the inclu- 
Lon of the above copyright notice. This software or any other copies 
nereof may not be provided or otherwise made available to any other 
arson. No title to and ownership of the software is hereby trans* 
srred, 

■je information in this software is subject to change without notice 
id should not be construed as a commitment by Digital Equipment Cor- 
jration, 

Lgital assumes no responsibility for the use or reliability of its 
jftware on equipment which is not supplied by Digital, 
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1,0 Introduction and overview 

This document is designed as a users guide to DDT version 41 in so far 
as it has changed from previous versions of DDT, It is not a complete 
users guide to all the wonders of DDT, just those new features which 
have recently been implemented (although directed primarily at new 
features only in DDT version 41, some documentation is included to 
describe other aspects of DDT which have been around for a longer 
period of time, but were never fully understood or otherwise 
documented). 

Throughout this document it is assumed that the reader is already 
familiar with DDT and the MACRO assembly language in general as well 
as the appropriate operating system(s). 

This is the first revision of this document, incorporating the addi- 
tional changes to DDT version 41 as of edit 260, 

2,0 Configurations 



DDT version 41 will run on KA-10's, Kl-10's, Kl-10*s, and KS-lO's ( » 
using no paging, Kl-paging, or KL-paging, with or without extended 
addressing in user or executive mode (user and file DDT's run only in 
user mode) with no special assembly needed, DDT version 41 must be 
assembled to run under either the TOPS-10 or the TOP5-20 operating 
system, 

It traditionally has been a goal to maintain one single set of source 
files from which all flavors of DDT are built. This goal has been 
maintained. 

Note 

TOPS-20 UDDT (and SDDT) now use memory locations 764000 
through 777777 (previously 770000 through 777777), but the 
starting address for DDT continues to be location 770000, 
This requires version 4 of the PA1050 "compatibility pack- 



age" 



• 



3.0 Memory and Address Control 

The single biggest change to DDT version 41 from earlier versions is 
in the realm of memory control and how the user addresses memory loca- 
tions, 

3.1 Extended addressing 

All flavors of DDT except FILDDT will run in any memory section. Full 
extended addressing is supported, as are "large" addresses - DDT will 
now accept a full 36-bit expression as an address although obviously 
only FILDDT can actually handle an address over 30-bits wide. In all 
cases the actual address must be positive (i.e., effectively a 35-bit 
address) , 
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,1.1 Symbol table restrictions 

■jere are certain restrictions however' which must be adhered to in 
rder for DDT to function correctly. The first restriction is that the 
ftnbol table logic is essentially section-dependent, i,e,, the symbol 
able and its pointers (,JBSYM»H6 and ,JBUSYsli7, also ,JBHSM=6 rela- 
Lve to the start of the "high segment") must reside (i r e., be mapped) 
i the same section as that in which DDT itself is running. Further, 
ie symbol table can be no longer than 128K words in length and must 
! RADIX-50 format, 

ich thought is being given towards the implementation of a totally 
sw symbol table scheme which would address all of these problems, the 
Ingle biggest one of which is simply how is extended addressing going 
3 be used - as a single fixed address space with one or more "global" 
/mbol tables (like the T0P5-20 monitor currently works), or as a 
sllection of independent sections each of which has section-local 
fmbols/symbol tables (whatever that means), or what? 

,1,2 Breakpoint restrictions 

le second restriction of which the user must be aware concerns 

reakpoints, since the hardware has no facility to unconditionally 

ransfer control to DDT using only 36-bits, DDT must be mapped into 

ich section (at the same relative address obviously) which contains 
ide into which the user wishes to place breakpoints, 

,iTS Location examining restrictions 

ren if running on an extended addressing machine if DDT is running in 
tction 0, then only locations within section (addresses to 
P7777) may be manipulated, DDT will make no effort to outsmart the 
>mblned efforts of the user and the operating system by sneaking into 
non-zero section even momentarily to do the memory reference, 

,2 Effective address calculation 

)T version 41 can calculate effective address references using either 
Local" or IFIW (Instruction Format Indirect Word) or "global" or EFIW 
extended Format Indirect Word) formats. In a normal DDT address-open- 
19 command ("/», "\", <TAB>, etc) a single <ESC> delimiting the 
Idress expression (e.g., "MOVE 3,9200(10)$/" or just "$£") instructs 
)T to treat the expression as an IFIW word and calculate the effec- 
Lve address exactly like the hardware would, were the hardware to 
tecute that 36-bit word as an instruction at location "," (whether or 
>t location "," is currently open), 

fo <ESC>'s delimiting the address expression instructs DDT to treat 
>e 36-bit expression as an EFIW word and calculate the effective 
Idress exactly as the hardware would, were the hardware to indirectly 
idress the 36-bit expression at location *," (whether or not location 
," is currently open), A strange, case can come up about which the 
;er should be cautioned - there is an ambiguity as to where (i,e,, 
la^section") to start the effective address calculation, DDT as- 
tmes the left half of "," (i,e,, the last location opened by the 
ler). If for example having opened location 0,,1234 which contains 
,4321 the user issues the command "SSC" then DDT will calulate the 
ifective address as the contents of location 4321 in section 
idexed by the right half of register 7, and if bit 13 Is on, treating 
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that word as an IFIW and continuing the address calculation. This,, 
although probably not what was expected, Is In fact exactly what the 
hardware would do since the indirect word came from section 0, Had the 
user opened location 1,,1234 (containing 7, ,4321) then DDT would take 
the contents of location 7004321 and continue from there. 

If no <ESO*s delimit the address expression, then DDT simply uses the 
full 36-bit expression as the address (e,g,, "30,, 30/" says open loca- 
tion 30000030 and "-1/" says open location 777777777777), Again, only 
FILDDT can actually reference an address greater than 30-bits wide 
(not that anyone has that much disk space, but the hardware will not 
permit an address space over 30-bits wide), and in any case the ad« 
dress must be a non-negative 36-bit Integer. 

There is a special case. in which DDT does something "kinky" - if a 
space was typed in entering the address expression, or if no explicit 
address was typed (i.e., the user is using the "last word typed" by 
simply typing only (for example) <TAB>), DDT will form the 36-bit 
actual address by using only the right half of the 36-bit address 
expression plus the left half of "," as the section number. This not- 
at-all-obvious behavior is so that the user can type in expressions 
such as "JR5T PAT<TAB>" and have DDT go to location PAT in the same 
section as the JRST PAT instruction rather than going to address 
254000000000+(PAT modulo 2**18), Another common usage of this "fea- 
ture" would be in chaining down linked lists where the link pointer is 
an 18-bit section-local address in the left half of a word. To do this 
the user may type "spSSQ/" (where "sp" means space). This is one oiE 
those cases where usefuilness outweighs cleanliness of implementation 
and documentation, 

3,3 Modifying memory 

Two new commands nave been added to facilitate DDT*s manipulation of 
the user address space, 

3.3.1 Automatic write-enable 

The SW or SOW command instructs DDT to, if the user attempts to depos-» 
it into a write-protected memory location, automatically attempt to 
write-enable the memory location, do the memory deposit, then finally 
re-write-protect the memory location (default for TOPS-10); the S$w or 
SS0W command instructs DDT to simply give an error indication if the 
user attempts to change a write-protected memory location (default for 
TOPS-20), For FILDDT the use of this command is restricted to non-file 
usage such as "DDT'ing" the running monitor/memory space. 

3.3.2 Automatic page-creation 

The $1W command instructs DDT to automatically try to create the page 
the user is trying to deposit into if it doesn't already exist (de- 
fault for TOPS-20); the S$1W command instructs DDT to simply give an 
error indication if the user attempts to write into a non-existant 
page (default for TQPS-10), EDDT and FILDDT doing super I/O or 
"DDT'ing" an ,EXE: file will NEVER attempt to create a non-existant 
page. For FILDDT. the user must specify patching the file when he 
starts FILDDT In order to be able to create new pages (e.g., extend 
the file or fill in a gap in the middle of the file (TOPS-20 only)). 
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,4 Page mapping and physical addressing 

i DDT version 41 all flavors of DDT support page mapping and address 
^location as well as register and physical address manipulation. All 
t these functions use some variation of the su/SSU DDT command. In 
eneral these functions may be mixed together (for example address 
^location and page mapping). 

**» Warning *** 

The.SU command syntax in DDT is totally different Cand main- 
ly incompatible) from previous versions of DDTi The user is 
MOST strongly urged to carefully read this section on memory 
mapping and addressing! 

.4.1 Physical addressing 

3T now has the concept of "physical" addressing in addition to its 
urmal "virtual" addressing. The $u command instructs DDT to use nor- 
ai virtual addressing (what it used to do); the $$U command instructs 
)T to manually track down the honest physical address rather than the 
Lrtual address space in which DDT finds itself running. Physical ad- 
ressing is really applicable only to EDDT or to FILDDT looking at 
inning monitor/memory (TOPS-10 only). User mode DDT (including EDDT 
ir^ng in user mode, MDDT (TOPS-20 only), and VMDDT (TOPS-10 only)) 
^dWlLDDT looking at a disk all treat $U and $$U identically. In 
tyslcal addressing location is not register (i.e., DDT's internal 
>py of user register 0) but rather physical memory location page 
ink box (that memory location on the hardware memory bus that 
jsponds to all address bits = 0), 

len the $5U DDT command is Issued "physical" locations to 17 become 
registers" to 17, For user mode DDT this means locations to 17 
scome DDT's registers rather than the user's registers (although the 
ser's registers will be properly restored on DDT-exit, SSU. merely 
Lrects DDT not to use the internal "fake" (i.e., user) registers), 
>r FILDDT this means file words to 17 (as mapped by the ,EXE 
Lrectory if used) become locations to 17 (normal for a data file), 

jbsequent issuance of the $U DDT command will redirect locations to 
t to being DDT's internal "fake" registers again, except for FILDDT 
>oking at an data file or doing super I/O to a disk, 

>te that for executive mode EDDT to utilize physical addressing the 
iging hardware must have been enabled PRIOR to DDT-entry. This re- 
tirement exists because EDDT, in order to access all of physical 
mory, needs to map the desired physical address into its own (execu- 
Lve) virtual address space, which it does by fondling the already- 
ctant page maps. For EDDT to provide physical addressing capability 
bthout this restriction would require 2 (3 if KL*paging) more memory 
tqi w be dedicated to EDDT for building temporary page maps, plus 
ipport code etc, 

>r FILDDT to examine/modify physical memory a 7,00 or later release 
t the TOPS-10 monitor is required; no release of TOPS-20 supports 
LLDDT'ing physical memory. 
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3.4.2 Page mapping 

AH flavors of DDT now support page mapping in both the KI- and the 
KL-tradition, EDDT in executive mode will dynamically figure out which 
style of paging is in effect and operate accordingly, AH other fla- 
vors of DDT (including EDDT running in user mode) will assume the mode 
of paging used by the operating system for which DDT was assembled « 
Kl-paging for TOPS-10 and KL-paging for TOPS*20, To select Kl-paging 
emulation the flgslOU command is used; to select KL-paging the flg$iiU 
command is issued? in either case if fig Is zero then. the paging 
emulation is disabled, if fig is non-zero then the appropriate paging 
emulation is enabled. 

In executive mode EDDT or FILDDT looking at running monitor/memory 
space DDT will internally utilize physical addressing in order to 
provide the user the true mapped virtual address space desired, 

3.4.2.1 Kl-paging - For Kl-paging (TOPS-10 default) the page mapping 
command for the executive virtual addressing space is (upt<Sept$ [03U 
where upt is the optional physical memory page number of the user 
process table (for setting the "per-process" addressing space - exec 
virtual addresses 340000 through 377777) and ept is the physical memo- 
ry page number of the executive process table, The user virtual ad- 
dressing space is selected by the uptSlU command. The command SU re- 
turns DDT to regular unmapped virtual addressing, 

3.4.2.2 KL-paging - For KL-paging (TQPS-20 default) the page mapping 
command for the executive virtual addressing space is ept$C03U where 
ept is the physical memory page number of the executive process taole,, 
or epxSStOlU where epx is the index into the SPT of the executive 
process table pointer. To select the user virtual addressing space the 
command is upt$iU where upt is the physical memory page number of the 
user process table, or upx$$iU where upx is the index into the SPT o& 
the user process table pointer. The command SU returns DDT to regular 
unmapped virtual addressing. 

To map a single section (256K address space) under KL-paging the 
command is either sec$2u where sec is the physical memory page number 
of a KL-paging section map, or sex$$2U where sex is the index into the 
SPT of the section map. 

Basically, under KL-paging, SOU selects the ept, Siu selects the apt,, 
and $2U selects a single section, A single $ indicates the physical 
memory page number and two $'s indicate an SPT index. 

3.4.3 Setting the SPT 

FILDDT will automatically define the start of the SPT from a disk file 
(assumed monitor dump) from the symbol "SPT" if it exists CTOPS-20 
only). The command sptseu specifies to DDT that the SPT starts at 
address spt, 

3.4.4 Register addressing 

The command acs$5u instructs DDT to use the 20 consecutive locations 
starting at acs as the registers (DDT maintains an internal copy o£ 
the registers so changing "register" 3 will not affect (for example) 
acs+3), FILDDT, wnen reading an .EXE file, will automatically load its 
internal "fake" registers as though the user had typed CRSHACS5U if 
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OPS-10 or BUGACS$5U if TOPS-20, Note that if physical addressing mode 
as been entered (the user has issued the $SU command) then the inter- 
al "fake" registers are ignored; if the user subsequently reenters 
irtual addressing (via some form of the $u command) then an acs$5U 
ommand may also have to be re-issued to get the registers back (this 
oes not affect the saving and restoring of the hardware registers in 
ser or executive DDT, only what DDT will use for typing out locations 
to 17). 

he command flg$3u explicitly controls the usage of DDT's internal 
fake" registers - if fig is then the "fake" registers are Ignored 
i.e., to 17 are taken from the true current addressing space), if 
ig is non-zero then addresses to 17 are taken from DDT's internal 
spies of the registers. 



ne SU command, except for FILDDT'ing a data file or doing super I/O 
a a disk, will return DDT to its internal "fake" registers. The se- 
sction of registers is completely independent of any page mapping in 
Efect. Changing virtual address spaces does not change the "regis- 
srs". 



■» executive mode DDT only the command n$4U w 
ind thus display) hardware AC block n (available 
5-10's). The user is warned that 7S4U on a KU- 
it " death (the microcode uses AC block 7), 
ssWre the ac block context to the state it wa 



,4.5 Address relocation and protection 

an aid to looking at data structures wh 
>inters as offsets rather than pointers as ab 
Ion 41 will allow the user to set both a base 

added to all addresses used in location examining commands and a 
rotection address beyond which the user "virtual" (note the use of 
virtual" here as meaning pre-relocated) address is illegal. This is 



roincidently) exactly analguous to the KA-10 hardware relocation 



rotection strategy, and in fact could be used 



111 switch DDT to use 

only for KL-iO's and 

10 will bring rapid and 

On DDT exit DDT Will 

s in at DDT entry. 



ich are formed using 

solute values DDT ver- 

relocation address to 



as such to "mimic" 



and 

the 



J KI/KL/KS-10 functionality on a KA-10 in executive mode. The form of 
lis command is bas$8U where bas is the base virtual address, and 
rt$9U where prt is the maximum address the user will be allowed to 
fpe in. Note that page mapping and address relocation and protection 
■e independent mechanisms, with address relocation and protection be- 
ig performed before any mapping is done. The protection address has 



> effect on the final 
irrently in effect. 



"physical" address generated by any mapping 



.4.6 $U command summary 

.1 sU/s$U commands take the following form: 



$U 
.ssu 
_jpt$C$3 COJU 
1 * - upt$£s3iU 

sec$C$)2U 

flg$3U 

acb$4U 

acs$5U 



Unmapped virtual addressing! 

Unmapped physical addressing 

Select executive virtual addressing 

Select user virtual addressing 

Select single section 

Select (deselect) internal jfake registers 

Select hardware ac block 

Load internal fake registers 
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9, spt$6U Select base of SPT 

10, bas$8U Set base relocation address 

11, prt$9U Set protection address 

12, flgSlOU Select (deselect) Kl-paging 

13, flgSHU Select (deselect) KL-paging 

where: 

1, acb sa integer ac block number 

2, acs := address of 20-word register block 
3,' bas := base relocation address 

4, ept : = executive process table page number 

5, fig := selection flag, zero to deselect, non-zero to select 

6, prt := protection (maximum allowable) address 

7, sec := section map page number 

8, spt := address of SPT 

9, upt := user process table page number 

3.4.7 Address checking (Executive EDDT only) 

EDDT version 41, when running in executive mode, now is much more 
extensive in validity-checking memory references. In particular, EDDT 
will not cause a NXM (page fault) trap to the resident operating sys- 
tem if the user types in an illegal (non-existent or unmapped) 
address, but rather will simply type its ubiquitous ?<dink><TAB> -error 
message. 

3.4.8 Address breaking 

DDT will no longer cause an address break to occur when examining or 
depositing a location at which an address break condition has been 
set. This applies only to "user" examines and deposits, an address 
break set in DDT will still cause an address break to occur, 

4,0 Specifying the start Address 

The $G command now expects a 36-bit address (obviously with bits to 
5 off) at which to start the user program. This means that the users 
of programs such as the TOPS-10 monitor which define symbols like 
" DEBUG= :<JRST .>" can no longer go either DEBUGSG or DEBUGSX at the 
users whim but must decide on one form or the other (the default 
obviously being to do nothing - i.e., to settle for the DEBUGSX form) 

5.0 Symbolic expression typein and typeout 

DDT version 41 has expanded the range of both symbolic typein and 
symbolic typeout. 

5.1 Symbolic typein 

The JSYS opcode (opcode 104) has been added to T0PS-20 DDT, as have 
all the TOPS-10 UUO's (but not the CALLI's etc.) for debugging pro- 
grams which run under the compatibility package. 



iT41 - DDT %41C260) users Guide to New Featured Page 10-9 

mbolic expression typein and typeout 

2 Multiply-defined symbol typein 

the user types an ambiguous symbol (a symbol defined two or more 
aces outside of the current local symbol table and not in the cur- 
nt local symbol table) DDT will issue an "M" error message, 

3 Selecting no local symbol table 

e s: command Issued without an explicit module name to use as the 
cal Cor "opened") symbol table will deselect any local symbol table* 
is is the initial state in which DDT starts* 

4 Symbol cache 

T now has a symbol "cache" of symbols recently used to type out 
lues. This cache is used primarily for typeout; typein win check 
e symbol cache for a matching symbol from the currently opened or 
cal symbol table, if no match is found the cache is ignored and the 
gular symbol table is used. The symbol cache is "flushed" on the 
suance of any $: command* 

5 Symbolic typeout 

T "*ow goes to great pains to find any possible user-defined symbol 
ui.jp? as an OPDEF) to match the expression DDT is trying to type out, 
e order in which DDT searches for a symbol match in symbolic typeout 
de for non-1/0 instructions iss 

Full 36-bit match; OP, AC, I, X, and Y fields (e.g., the TOPS-20 

monitor calls such as GTJFN) 

OP, I, X, and Y fields (e.g., the TOPS-10 monitor calls such as 

FILOP.) 

OP and AC fields (e.g., the TOPS-10 monitor calls such as INCHWL 

or "instructions" such as HALT) 

OP field only (e.g., user UUO's or "OPDEF XMOVEI CSETMI3") 

DDT's internal hardware opcode table 

e order in which DDT searches for a symbol match in symbolic typeout 
de for I/O instructions is: 

I/O OP and DEV fields (bits to 12 - e.g., KL-10 APRID or KS-10 

RDCSB) 

Regular Cnon-I/O) OP field (e.g., KS-10 UMOVE) 



ASCII typeout 

T version 41 adds the typeout mode commands $8T and $9T to typeout 8 
t ">CII or 9 bit ASCII respectively (i.e., pick up 8 or 9 bit bytes 
d%€ype" them straight as is - which with current TOPS-10 and TOPS- 
operating systems means as 7-bit ASCII), 
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7.0 Command files 

The SY command (TOPS-10 DDT only) has been changed somewhat, both in 
input and output Clogging) functions. 

7.1 Command input 

If the user does not type a 36-bit expression to be used as a tfile 
name (such as $"»FIIiNAM"$Y) but just types $Y by itself then DDT will 
prompt with "File: ", After the prompt the user can enter a TOP25-10 
file specification in the form dev:name, type [directory] /switches where 
[directory] can of course contain SFD's, 

7,1.1 /A switch 

The /A switch instructs DDT to abort the command file if a DDT-detoct™ 

ed command error occurs (such as reference to an undefined symbol),, 

7.2 Command output Clogging) 

When reading a command file C$Y command) DDT will no longer "log" all 
output onto device LPT: but rather just type out onto the user 
terminal, 

8.0 Automatic patch insertion 

The automatic patch insertion facility Cs< and $> commands) are basi- 
cally the same as in version 40 of DDT with only minor differences, 

8.1 Patch opening 




8.2 Default patching symbol 

The list and order of default patching symbols which DDT uses when the 
user does not supply an explicit patching symbol is now: 

1, PAT CTOPS-10 EDDT only) 

2, FFF CTOPS-20 EDDT and MDDT only) 

3, PAT,. Call flavors) 

4, PATCH call flavors) 

5, PAT Call flavors except TOPS-10 EDDT) 

8.3 Default patching address 

If the user does not supply an explicit patching symbol and DDT Is 
unable to find one of the default patching symbols then the addresas 
specified by the right half of location ,JBFF Ceven on TOPS-20) is 
used. On patch close C3> command) if the patching address was default- 
ed to via .JBFF, then both the right half of location .JBFF and the 



DT41 - DDT %41C260) Users Guide to New Features Page 10-11 

utomatic patch Insertion 

e^haif of location ,JBSA are updated, 

.4 Patch closing confusion and restriction 

1th DDT version 41 it no longer matters how (when) the user types the 
> command, either immediately after the final word expression, or 
fter a <CR> or <LF> to terminate the final word expression - DDT will 
ever generate a word for free, 

nere is a very obscure restriction however on the use of the # 
smmand in conjunction with the $> command. If the user is referencing 
i undefined symbol in the expression for the last word of the patch 
len that expression must explicitly be terminated in such a fashion 
s to close the location before terminating the patch. For example, 
*OVE T1,BLETCH#$>" is illegal but "MOVE Tl ,BLETCH#cr$> (where »cr" 
idicates a carriage return) is ok, 

,0 Breakpoints 

le breakpoint logic in DDT version 41 has been extensively revamped 
i order to support extended addressing. The default number of break- 
>ints is now 12 (decimal); and can be set (by defining the symbol 
iPsnumber of breakpoints) arbitrarily high (within memory space llmi- 
itions) rather than being limited to 9 or 36 (decimal) depending on 
>i<"-*> code restriction one choose to believe, 

,1 Setting breakpoints 

>T can now set a breakpoint in code running in any section with two 
(strictions: 

If DDT is currently running in section then breakpoints can 
only be set in section (see section 3,1,3 above), 
DDT must be mapped in the section containing the code In which 
breakpoints are to be placed (the logic of this is that since 
there is no way for DDT to cause unconditional transfer of con- 
trol to DDT with only 36 bits some portion of the section address 
space must be devoted to DDT; therefore, given this restriction, 
one might just as well put all of DDT in that section since it 
makes for a cleaner and simpler Implementation), Note that this 
does not mean DDT must be running in that section, but merely 
that DDT must be mapped in that section! 

does not matter into how many different sections the same code is 
ipped as long as DDT is mapped into the same sections since DDT is 
ectlon-independent". For example (taking the TOPS-20 monitor which 
Ps section and section I identically) if a breakpoint is set at 
tdress 1004567 (or i,,4567) but the PC was 4567 (or 0,,4567, i.e., in 
ction rather than section 1) when the breakpoint was executed DDT 
es not care (as long as DDT is mapped in that section, which in the 
ar re of the TOPS-20 monitor it is). 



e syntax for setting a breakpoint is now opn<bpt$nB where n is 
tionai and. If specified, declares the breakpoint number to be as- 
gned to that address; bpt is the 36-bit address at which to place a 
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breakpoint; and opn Is an optional 36-bit address to open and display 
upon execution of the breakpoint, The syntax was changed because two 
full 30-bit addresses could not be squeezed into two halfwords. 

DDT will no longer assign two different breakpoints to the same ad- 
dress, either accidentally or under user, control - if the user at- 
tempts to set a breakpoint at a location at which a (different) 
breakpoint is already set, the old breakpoint is cleared first, 

9.2 Breakpoint typeout 

Upon execution of a breakpoint DDT will now always typeout the user 
Instruction (in instruction format regardless of the permanent typeout 
mode) at that breakpoint and set "." to the breakpoint address, If, f 
further, opn was specified as in section 9,1 above, then DDT will also 
display the contents of location opn In the permanently set typeout 
mode and "," will be updated to opn (with the breakpoint address it- 
self becoming the previous PC sequence and so available via the $<CR> 
etc, commands}, 

9.3 Examining breakpoint locations 

The SnB command continues to be the "address" of breakpoint n»s data- 
base, but SnB is no longer equal to Sn-lB+3, The breakpoint database 
of interest to the user now has the following format: 

1, snB+0/ If nonzero the address for breakpoint n 

2, snB+1/ The conditional break instruction (break if skips) 

3, snB+2/ The proceed count (break on transition to 0) 

4, snB+3/ If greater than or equal to zero then the address to be 
displayed 

The rest of the breakpoint data base should not be of use to the user, 

9.4 Unsolicited breakpoints 

DDT version 41 has a new breakpoint facility - the ability to handle 
unsolicited breakpoints (i,e f , breakpoints that DDT did not itself 
set). If control passes to location S08PT+1 (SOBPT is a global DDT 
symbol) then DDT will act as if a breakpoint had been set at the 
address-1 contained in location SOBPT, The address in SOBPT must be 
setup as if the cpu executed a JSR SOBPT instruction - If in section 
then flags,, PC otherwise just global 30-bit PC, After "hitting'' an 
unsolicited breakpoint the user can proceed with program execution 
with the $P command (all arguments to the $P command such as proceed 
count or auto-proceed (SSP) are ignored). 

Although this facility gives programs the ability to cause breakpoints 
at any time (thus getting Into DDT with the program state carefully 
preserved) it is intended to be of most use in conjunction with an as- 
yet-unimpiemented monitor command (such as control-D) to "force" a 
breakpoint on a program without having to control-C/DDT the program. 
Then the user could simply continue with the program by typing SP, 
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3 Hp» Single-stepping the program 

ie sx DDT command has been significantly modernized Cand sped up in 
sneral) with version 41 of DDT, 

>,1 New opcodes 

!?^ D *? P ; a S?? D ',^ UB# K D !! Ul " and DDIV instructions have been added to 
t ?7, ta la although double- and quad-word integers (for DADD etc.) 
!?*«!, typ ? d out as two or f0 «r single words rather than one big 
Utiple precision integer. All of the extended JRST-class instruc- 
,ons are correctly simulated/traced. A user-UUO being executed in a 
>n-zero section is simply xCT'ed and is not traced. "cuteo « a 

•2 Byte-manipulation typeout 




•3 Effective address calculation 

LS L a i! a H.K Cal f!! Xat ! s the 6 "ective address of the instruction 

, «I X ed rather than 3ust blindly "doing it" in order to both pre- 

?W* Li^LJ et I ln ! a 2 1Uegal memory reference as well as to mate 

J7 independent of the section in which the user PC resides (i.e., 

L«°!?^ 0t „K h f* e . t0 be raapped Into the user PC section to handle 
es although if the user PC is in a non-zero section then DDT must 
in a non-zero section). Besides, it's usually faster tooi 

.4 KS-iO i/q instruction trace 

s KS-io specific I/O instructions which reference the UNIBUS (execu- 
te mpde pnly) are not traced, only the contents of the register 
scified in the AC field are displayed. Since the UNIBUS device reg- 
;«I S ^ a ?„ 5! reference-volatile (i,e,, merely referencing one can 
!!.,J \ll change - such as the DL-H data registers) DDT does not 
eout the contents of the referenced UNIBUS address. Further, since 
L5 il C £ * ddress of tft e. instruction is not calculated in a 
ndard format (at least as far as DDT is concerned) the effective 
Jress Itself is not even displayed, 

>5 PC skipping 

•J?D^" Se * i2 $tr Ii" lon being sx ' ed s,clps then D &* will now typeout 
•KIP>" if the PC skips by one location, or "<SKIP n>" if the PC 
ps by n locations, where n Is less than or equal to the DDT assem- 
' parameter SKPMAX (by default 3), If the PC changes more drastical- 
r.nan that (e,g,, goes to a smaller address) DDT will type »<jujxp> 

T» 6 clQ * 



6^RCAL/ERJMP 

(TOPS-20 only) will now handle instructions followed by either an 
AL or an ERJMP instruction (which Is really just a 72-bit instruc- 
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will .as "™ UlpUa Ci.... th. PC i"«««.nt«d by 2 rather than U 
™ ... „„♦. ji.nixv the ERCAL or ERJMP instruction, it tn«. 
Jnstruciion^oes iaSe^he'error juSp then the ERCAL or ERJMP ln.truc- 
Man will be displayed, if an ERCAL instruction then register 17 will 
aisS le iiSplaJeS) anS'tne PC will be changed to the error address. 

DDT will print »<ER5KP>" rather than showing the ERCAL JJ E RJMP in« 
s?Ju?uJn P since DDT has no way of telling whether or not the instruc- 
tion Itself caused the skip (as in a SKIPA) or if the *C •ereiy " 1X 
through" the ERCAL or ERJMP instruction (as in a successful MOVE). 

Users of EDDT and MDDT should be cautioned about $Xing i^ructions 
followed by an ERCAL or ERJMP in non-zero sections - the monitor has a 
;-ni«nrv to transfer control to the error address in section 0, which 
wiU cause a ITghlI 'because d5t (running in executive mode) does non- 
zero lection things thinking it is still in a non-zero section. 

10.7 SX'ing an INIT 

~«« 4i, -«« i.t. fh. „«r 6X an INIT (TOPS-10) monitor call, DDT will 
^"St-UlcSSi lf"S. HH til" « <S«P 3> 1* th. INIT .uccaaos. 

10.8 $X speed up 

Bv huiidina into DDT a table of instructions which can. cause the state 
of SXiSXSn 5o!l5 to change, and assuming the state of the world does 
not cnanSe If the instruction being SX'ed is not so marked, the time 
rlSulreS "Jo SX an instruction is cut by roughly a factor of 10. This 
results in a dramatic performance increase especially for EDDT 
10 's where waiting for the console front end to switch between 
secondary and primary protocol is very time-consuming. 

10.9 Repetitive SX'es 

The SSX command now takes an optional address range, formally $$ X will 
terminate when the user PC inclusively enter th f,ange .♦! t o .♦ 
qkpmax f default value of SKPMAX is 3). The user may sP , - c ^y 
lw5J5r>«X "Sere i» the lower address boundary and upr is the 
upper address boundary which, if the user PC ever inclusively enters 
tSeranae so specified, terminates the $$X. If only lwr is specified 
then uS? defaults to lir+SKPMAX. This command is very useful for re- 
covering from having SX'ed a (for example) PUSHJ instead of having 
SSX'ed the (for example) PUSHJ, 

10.10 SX'ing from instr$X 

If the user SX'es a return from a subroutine which was «njered by 
doing an instrSX (for example "PUSHJ P,SUBRTN $ X where fUBRTS has a 
breakpoint in it) then DDT simply "returns" "om the original instr,|X 
rather than preceding to SX the internals of DDT itself. This is a 
very obscure condition so don't worry too much about it. 
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P , $$X status 

DT will now respond to a ? character being typed during an $$X se- 

nence by typing "Executing? " followed by the current user »pc" and 

istruction being executed. Typing any other character terminates the 
$X immediately, 

>.12 $X PC 

ie s, command now acts like the , command only $, returns the value 
I the $X PC (i.e., the address of the next instruction to be $X'ed). 
He $$, command returns the previous $, value (useful for $$.<$$X as 
\ section 10,9 above) • 

,0 searches 

►st of the differences in how DDT version 41 handles searches are 
mply bug fixes, not major changes in the logic of searching, 

•1 Non-existant pages 

»T version 41 now simply skips over pages which don't exist in the 
dress space being searched, rather than terminating the search as 
on as a hole has been found, 

•^Missed matches 

e bug which caused TOPS-20 DDT to miss many valid matches is fixed 
DDT version 41, 

.3 Effective address searches 

nee almost all address calculations start with an IFIW basis Cwith 
e exceptions being such things as interrupt vectors and the like on 
-10's or KS-10's), DDT version 41 will assume that each word it 
amines is an Instruction and perform an IFIW effective address cal- 
lation. The final result must match in all 30 bits (actually 
ternaily DDT will do a full 36-bit compare so the address being 
arched for had better not contain anything in bits to 5), 

,4 Address limit defaults 

th the advent of extended addressing and physical addressing the 
3ress limits are defaulted somewhat differently than from previous 
rsions of DDTj 

EDDT, MDDT (TOPS-20 only) , UDDT, and VMDDT 

1* Lower Limit: <current section>,,0 

2, Upper Limit: <current section>, ,777777 

w'XLDDT looking at an , EXE file 

1. Lower Limit: 

2, Upper Limit: highest virtual address mapped 
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3, FILDDT looking at a data file 

1, Lower Limitt i - 

2, Upper Limit: highest word written in file 

4, FILDDT looking at dislc structure/unit 

1. Lower Limit: .. 

2, Upper Limit: highest word in disk structure/unit 

5, FILDDT looking at runing monitor 

1, Lower limit: 

2, Upper limit: 777777 

6, FILDDT looking at physical memory CTOPS-10 only) 

1, Lower Limit: 

2. Upper Limit: Highest extant memory address 

As with any defaults not all cases will be properly "guessed" by DDT. 
in particular if the user has mapping or address relocation in effect 
Jhe P "r1u^l Ldress range so produced may have nothing whatsoever in 
common with the address limit defaults chosen by DDT. 

11.5 Search matches 

DDT will leave each address matched by its search on Jhe'pc stack- 
available to $<CR> etc. commands. When the search is terminated DDT 
will set "." to- the last address searched, 

11.6 Searching status 

DDT will now respond to a ? character being typed during a search by 
WlSg"a22JchlnS? " followed by the current location and value being 
searched. Typing any other character terminates the search immediate- 
ly. 



12.0 watching 

DDT version 41 allows the user to "watch" a location, waiting for it 
to cnlnge. Although primarily useful for FILDDT'ing the running on - 
tor. it ii present in all flavors fo DDT for completeness. The syntax 
olihe washing command is expSV, where exp is the address to be 
watched. If no explicit address is specified the last location opened 
by the user will be used. 

Upon initial issuance of the $V command the location is displayed. 
Thereafter the location is continuously monitored, an £ will b« J** 
Dlaved every time its contents change. In user mode DDTs Cand this 
includes TOPS-20 MDDT as well) the location is checked once * clock 
tick (approximately 50 to 60 times a second), in exec mode EDDT the 
location is continuously being monitored - no "pause" is attempted. 



DDT 



will respond to a ? character being typed during an $V sequence by 
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y^>g "Watching: ." followed by the current location and contents 

eiTTg watched. Typing any other character terminates the $V immediate- 



• 



3.0 Zeroing memory 

he algorithm used by DDT previous to version 41 has only limited 
sefulness in today's modern virtual world (especially on TOPS-20). 
iU*«fI\J° J?2 ld " brea * ln 9" already extant control or MIC files which 
ay use the $$2 command it remains unchanged. A new command has been 
Bpiemented - lwr<upr>exp$z where iwr is the lowest (starting) ad- 
ress, upr is the highest (ending) address, and exp is the 36-bit 
lantity to deposit in each word inclusively bounded by iwr and upr. 
>th iwr and upr roust be specified. If exp is not specified then is 
»ed as the default, 

special note: The creation of zeroed pages (which formerly were non- 

tistent) by the $z and S$Z commands is under the control of the 

itomatic page create flag (i,e, the $iw and $siW commands - see sec- 
.on 3.3*2). 

>T will now respond to a ? character being typed during an $Z 

(quence by typing -Zeroing: " followed by the current location and 

ilue being "zeroed". Typing any other character terminates the sz 
imp-Uately, 

.0 special masks 

T version 41 (it actually started with DDT version 40) has several 
w masks" (for lack of a better name and/or command) of interest to 

e ^f™ None of tnese mas,cs are currently dlsplayable (e.g., "$3M/») 
FILDDT although they may be set normally, 

•1 $0H - search mask 

e operation of the search mas* continues unchanged. The search mask 
y now be referenced by either the $M (old style) or the $0M com- 
nds. The default value remains 777777777777, 

.2 $1M - TTY control mask 

i S £nf!L Controls 5 P ecjLal TTy behavior (primarily TOPS-10 and exec 

3e EDDT) , 

.2.1 Tab separator display 

t 17 controls whether DDT will print its usual <TAB> or three spaces 

r the <TAB> separator, A (the default) selects three spaces, a l 

LCClS St >TAB/| 

r? *>. Tab simulation 

:\rf controls tab simulation. A selects literal <TAB> characters 
>e v , the terminal handles <TAB> f s directly, a i selects space-fill 
stead. This condition is automatically set for user mode DDT's (in 
sr mode <TAB>s are always output literally) - it is only useful to 
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manually set tab simulation in exec mode EDDT. 

llfil R con?rols n rubiut (and *W) operation. A selects "hardcopy* 
oiL^ioSfSS? will echo a -V character and the character being 
dete^ed? a 1 will caule ruSouts to echo as a backspace, space, back- 
space sequence! ih!s condition is automatically set for user mode 
nn?'s (if TTY DISPLAY Is set then rubouts echo as < BS> 1 SP ><5! 
?S only useful to manually set fancy rubouts in exec mode EDDT. 

14.3 $2M - Offset range 

ts. ifi-hit "masie" in this case is really a value, used as the maximum 
oflset .iie.Ku tor typing addresses in the form symbol+of fset. The 
default offset is 1000 (octal). 

14.4 $3M - Byte mask 

fied 8-bit bytes (preceded by the leading 4-bit byte). 

t5,0 RADIX-50 symbol typeln 

Since prehistoric times DDT has supported RADIX-50 W"«>ol typjin, Mt 
that fact was never documented. The syntax for using a RADIX-50 symbol 
» an -b i?em in an expression is sym$5» where sym Is the desired 
RAD?X-50 symbol. For example, to search for all occurences of the 
symbol PAT., the DDT commands 37777,, -i$M (only look at low-order 32 
bits) and PAT..$5"$W suffice. 

16.0 New DDT runtime information 

Several new words have been added to DDT's runtime table describing 
?he state of the machine upon (executive "ode only) D DT-en W. Jhetj 
words are all accessible via the DDT command $I+offset (not available 

APR CONI word 

PI CONI word 

Mask of PI channels turned off by EDDT 

Executive virtual address of EPT 

Executive virtual address of UPT 

Executive virtual address of CST 

Executive virtual address of SPT 

Original AC-block word (DATAI PAG) if acbS4U 



in 


FILDDT): 


1. 


$1-01/ 


2. 


$1+00/ 


3. 


$1+01/ 


4, 


$1+02/ 


5. 


$1+03/ 


6. 


$1+04/ 


7. 


$1+05/ 


8. 


Sl+06/ 
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7^ Hir 0bsolete commands 



ie executive mode paper tape facilities (*R, $J, and $L DDT commands) 
re no longer supported. The code is left in the source file for 
iference purposes but will soon be removed. 

U0 FZLDDT startup and commands 

CLDDT is a special version of DDT with the facilities for "DDT'ing" 
idress spaces other than its own, such as disk files and in particu- 
»r .EXE files, FILDDT has existed for years but has always been off 
» the background as a specialized "tool" for the exclusive use of 
>nitor programmers looking at crash dumps. With DDT version 41 FILDDT 
; now a general purpose utility for use by the "general public", 
irticularly people wno have databases resident in disk files C.REL 
les for example), 

i.l Symbols 

t of efficiency considerations FILDDT builds the symbol tableCs) it 
11 actually use at runtime in its own address space. Virgin FILDDT 
s no symbols (the symbol table (if any) for FILDDT in FILDDT.EXE is 
mpletely independent of the address space being FILDDT'ed and does 
t count). There are special commands to instruct FILDDT to extract 
n" build internal-to-FILDDT copies of) symbol tables from .EXE files 
e^pfeelow). Once FILDDT has setup its internal symbol table(s), it 
y then be SAVEd with the internal symbol tablets) for later use by 
iting to monitor level (with the *Z FILDDT command) and typing the 
AVE" command, 

,2 TQPS-io 

en FILDDT is started it will prompt "File: ", The user may at this 
me optionally enter a standard TOPS-io file specification in the 
rm devsname.typefdirectoryl/switch. At least one function switch is 
ndatory, SFD's are of course legal in the directory specification, 

,2,1 /D command 

e /D command or function switch instructs FILDDT that the file 
ecified is a data file - i.e., do not map the file as an .EXE file 
a use real file words to 17 for locations to 17, 

,2.2 /F command 

e /F command or function switch instructs FILDDT to "DDT this file 

/way", it Is useful only in conjunction with the /s command or func- 

an switch which normally re-prompts for another file specification. 

ed in conjunction with /S (which implies an ,EXE file) FILDDT will 

s the file from which symbols were extracted as the file to be 

)T'ed". 

rC 1 /H command 

s^fi command or function switch instructs FILDDT to type out a brief 

Lp text, abort the current command, and- prompt the user for another 

nmand. 
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Hi 2 }" com™? function switch is appliec » to a Job number rather 

access the Specified job's address space the success or failure of any 
g15en memor y reference is dependent on. the job being resident in main 
memory - S'tS. job Is swapped out or if the memory reference s to 
page which is paged out the memory reference will fall. This is <i 
privileged command. 

Tne^M command"^? function switch instructs FILDDT to -DDT- the cur- 
rently running monitor and physical memory address space (controlled 
SJ use of the SU and $$U commands). This is a privileged command. 

The 2 )* commander function switch instructs FILDDT to enable for writ- 
ing as well as reading the specified address space. Note that DDT s 
internal fake registers are always writable. 

ihe^S com^ol function switch instructs FILDDT to only extract the 
symbol table from the file specified, "placing any ^symbol table 
FILDDT may already have. Unless .overridden by the inclusion of a /F 
command FILDDT Sill, after having read the symbol table, again prompt 
the user for the next FILDDT command. 

The*/? commanTol function switch is applied to a file structure or 
disk unit only rather than a complete file specification and indicates 
to FILDDT that the user wants the entire physical address space repre- 
sented by that file structure or disk unit name independent of any 
-file structure mapping" normally imposed by the monitor. This is a 
privileged command. 

18.3 TOPS-20 

with DDT version 41, FILDDT on TOPS-20 runs in native mode, and in 
parJlcSIa?? uses the PMAP monitor call for all regular file access. 
fIlddt will also type a brief message telling what address space is 
about to be "DDT'ed" before going into DDT mode, 

18,3 „1 DRIVE command 

The format of the DRIVE command is: 

DRIVE (FOR PHYSICAL I/O IS ON CHANNEL) C (UNIT) U 

The DRIVE command allows examination of the disk unit u on system 
channel c without regard for whether it is mounted as part of a f i ; e 
structure, or indeed whether it even has the necessary information s»o 
that it could be so mounted (as if the HOME blocks were wiped out). 
It, however, the drive is part of a mounted file st ructure, FILD1 T 
will type a message indicating the structure to which it belongs. This 
is a privileged command. 
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8*^2 ENABLE DATA-FILE command 

he ENABLE DATA-FORMAT command Instructs FILDDT to treat the file as 
ure data, even if a valid .EXE directory is detected, and in particul- 
ar to use real file words to 17 as locations to 17, 

B.3.3 ENABLE PATCHING command 

le ENABLE PATCHING command instructs FILDDT to enable any subsequent- 
L S S e S if i ed add 5* ss s P ace £ <>r Patching (writing). This command Is 
jnored when looking at the running monitor since there is no monitor 
ill to "poke" the running monitor, 

},3.4 EXIT command 

)f™ IT coramand instructs FILDDT to return to command level, if 
LDDT has an internal symbol table (due to a previous LOAD or GET 
[LDDT command) then a SAVE command will save FILDDT with the symbols 
'e-loaded. 

1.3.5 GET command 

ie format of the GET command is) 

GET (FILE) filespec (optional switches) 

e GET command instructs FILDDT to set up the disk file filespec as 

e «Jf»f!»! SSJf.V be " DDT ' ed "' * s modified by the optional switches 
previous ENABLE commands. The available switches ares 

,%rS.l /DATA - The /DATA switch is equivilent to a previous ENABLE 
TA-FILE command, 

.3.5.2 /PATCH - The /PATCH switch is equivilent to a previous ENABLE 
TCHING command, 

•3.5.3 /SYMBOL - The /SYMBOL switch instructs FILDDT to extract sym- 
Is from the specified .EXE file before "DDT'ing" the file, discard- 
g any symbols that FILDDT may already have. This switch is legal 
*y wxtn ,exe flies. 

,3,6 HELP command 

!«? E wf c £?™ d instruc *s FILDDT to type out a short summary of the 
allable FILDDT commands, 

•3.7 LOAD command 

b format of the LOAD command is» 

LOAD (SYMBOLS FROM) filespec 

s LOAD command instructs FILDDT to extract symbols from the disk 
Le filespec, which must be an .EXE file, then to return to FILDDT 
nmand level. This command is legal only for ,EXE files, 

,3,8 PEEK command 

W E *f omrnand instructs FILDDT to use the currently running monitor 

.5!i.?2 d w'f.. , 5 a f e t0 ? e HDDT ' e <l", The address space so available is 

renciy limited to monitor executive virtual addresses to 777777, 

ice the PEEK monitor call will only accept 18-bit address arguments 

executive virtual addresses. Physical memory addressing is not 
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available. This is a privileged command, 

18,3,9 STRUCTURE command 

The format of the STRUCTURE command is: 

STRUCTURE (FOR PHYSICAL I/O IS) Str: 

-file structure mapping- normally imposed by the monitor. This U m 
privileged command. 

18,4 Defaults 

Following is a list of the various defaults supplied by FILDDT: 

1 dsk- is the default file device unless super I/O is specified 
' ?whl C h reauires an explicit file structure or dis* unit name). 

C ™£ i/r2e Selault file type or extension unless either a data 
2 ' me or sSpe? 1% is specified, in which case there is no default 

3. Ih^de^uirdlrertlJrU the user's default directory. 

I] ^ e -o P DT^n^ d ar:^l SIT ind r FrD°D n T ly does not already , haV e a 
symbol table, extract the symbol table (if any) from the .EXE 

!i l H A nH?«A« a „ fxf file and the symbol CRSHAC (if TOPS-10) or 
6 * b5ga« I^TOpIUo) ex sts! give a -free- CRSHACS5U or BUGACSS5U 
SSJSnd If tha CRSHAC/BUGACS symbol does not exist then use file 
command, it tne i.BBn«wBu«nv U j dir«etorv for lo-ca- 

words to 17 (if any) as mapped by the • E ^ m "^^? r ^ x ;°ts then 
tions to 17. For TOPS-20 only, if the symbol sft exists tnen 
also give a free SPT$6u command as well, 

18,5 Other FILDDT-specif ic commands 

Following are the commands which are unique (or different) to FILDDT. 

ine 5 4 commanr n instructs FILDDT to exit the current address space and 
prompt the user for a new address space. The *E command is equivalent 
to a *Z, START command sequence, 

&'4 ;:.£rtl!.tr«:t. riLDDf to exit to ...it.r level •».>»«!»« 

written out any changes to the current file (if any). It is raos>t 
W imPor e tan? U tha? n the h :s!r exit only via "Z (or «E which does an implicit 
-z) In order to guarantee the integrity of the file data cit anyj « 
-C can leave J file in an indeterminate state (some changes written 
out to the disK and some not). 



DTAi - DDT %41(260) users Guide to New Features p-ae io->* 

ILDDT startup and commands Pa9e l0 23 

tJSfif 1 ?! aJ e ?Iuit h %K"°^ ?! Bdit i 9 V i f the *****«! **** surface 
tse.it is at tauit, then it is probably hopeless). 
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SUBROUTINE CALLING - JSYS 

*?? i1: ^~ Ca11 JSYSes raa Y be used in user or monitor code. 
All ACs are preserved over a JSYS call unless an exolicit 
statement to the contrary appears in the JSYS description. 

rSn-fJ I ': hai 12 ed °?? r a JSYS cal1 onl y when values are to be 
returned to the caller. 

The JSYS name shall appear as the opcode in the statment 
which performs the call. The JSYS mnemonic includes the 
instruction field, so no other fields are supplied by the 

US9T • 

Unimplementad JSYSes will invoke the illegal instruction 
sequence (with error code ILINS2) . Defined and implemented 
J SYSes will return to caller +1 on success, or will invoke 
the illegal instruction sequence on failure. The illegal 
instruction sequence recognizes an ERJMP or SRCAL following 
the sailing JSYS and causes the appropriate action. If the 
following instruction is not an SRJMP or ERCAL, an iUeoal 
instruction interrupt is requested which will be handled "bv 
the executing fork if enabled, or otherwise cause a forced 
i-ork termination. See paragraph below on JSYS returns for 
proper indication of JSYS failure. 

All constant values, bits, and fields of JSYS arguments 
2£f.™ e Bnan, °ni« defined according to the rules in 
MONSYM. The JSYS code itself shall use these svmbols for 
loaaing arguments, testing bits, etc. 

When writing code to implement a JSYS, the following 
conventions shall be observed: 
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t. The entry point of the JSYS is defined by a global 
Sg which consists o£ a DOT concatenated with the 
symbolic name of the JSYS , e.g. .GTJFN::. 

2. The first statement of the JSYScode ;**"*• MC =»* 
(Monitor Context S^Try) . This **5f lis £* 3 *7* 
normal JSYS context for a "slow" JS YS. At th s 
writing, MCSJIT is a null macro and the JS £S nt.y 
procedure is invoked automatically. The use or 
MCSNT is reauired so that this implementation may 
be changed in the future if necessary. 

■? All calmer ICs are automatically preserved by the 
aiLv and exit "ocadures. Therefore JSYS routines 
"SToSlfilSill? rU»l"d «0T to -ve and restore 
the ACS. The contents of the caller ACa 1-4 a: e 
copied into the callee's ^s. No callee AC. , a ; a 
copied back to the caller's AC block on r ta.n 

Sciions^ausf be Sad to ?eturn any values to 
the caller. S.g. , 

UMOVEM T1,T1 ;store monitor Tl into user Tl 

x or*vious context instruction nay also be used at 

U "SSS to fetch the "i^ 1 ";"^;,^^; 

caller's ACs unless they nave ceen ex^-ici --/ 

chined by a previous context store operation. 
- • g « / 

UMOVTS T2,T1 ; load user Tl into monitor T2 



- UMOVZ, UMQVEM, XCTU [instruction! 



11-2 



TOPS20 Coding Standards 

4. Return from JSYS code should be effected bv the 
statement • une 

MRETNG ;Monitor RETurn Good 

caUer ran tf? rS 11***^***1} se ^ enc * (returning 

aSem.ful LmJ*t- * Ul ? be USed t0 indicate 

successful completion of the JSYS. If the JS^S 

ns«.sr.h:uid"gi t sSd? uccM " fuiiy ' the ^^ 

ITERR errcod ;causes an Instruction Trao 

;ERRor, leaves 

,*the error code in LSTERR 

Slv5 ai ?J? ther statements are defined which effect 
They are« UCnS aCCOrdin * t0 a ?™vIou« convention? 

RETERR errcod ; RETurn ERRor, return 

;caller +•! with error code 
;left in AC! and LSTERR 

EMRETN errcod ;Srror Monitor RETurn, return 

/caller +1 with error code left 
;in LSTERR 

bS"!U h 5 U ^ "°* be used ia n9W JSYS c ^e but may 
be needed if existing JSYSes are modified. Y 

All error returns shall include an error cads 

r^hTaoL ?} C 5 3haU be dSfined "« MONSY M .^ d : 
if uhe appropriate error code has already be«A 

omit*l ^ t0 ^ Ci '„ then the e "=° d futdmay be" 
omit.ed from the above and the contents of aci wiU 

oth.^dEn JfjS* f rr f r C ° de * No JSYS sha11 "turn 
occurring i# 0r a «i n !?f uct i on trap ' therefore no 
SIS "2e? (?) 3h ° Qld aVer be quired in 

When invoking a JSYS error return, it is not 

•s^riha^r* -^-"V entities' fro'm the 
s.ack. The successcul return however, should be 
given only when the stack is properly cleared. 
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SUBROUTINE CALLING - Internal monitor routines 

,, »* - «? xcs for all inter- and intra-modula 
The allocation of ACS -or 
subroutine calls shall be; 

*Cs 1 2 3,4 - General temporary, may be clobbered by 

subroutine. 

jx --*. .h 3 nAi<! bv subroutine (or 
AC s Z, 5-15 - ^^ed^nd^rstofertfnecessary) . 

AC IS - Temporary, used by JS f ^f^^bv'other 

AC ia procedure and reserved for use oy 

call/rstwn procedures. 

AC 17 —Global stack pointer 

for subroutine mechanics as follows. 

,«!/. {- PUSKJ 9,) shall be used to call 
^subroutines, e.g. CALL SUB a. 

•RET' (- ?GM P '> sha11 bS USed C ° CStUrn ^ Sr3m 
subroutines . 

»q»"W shall be used to return *2 «*«« 

subroutines. RSTSKP is equivalent wo . 

JKST C ACS fl(P) 
R£T1 

.RST3AD errcod' shall be used « '"^I,^? coSe 
error code from a subroutine. f * f " r ;^ rns 
field is optional as with -•= «"- c 
above. RET3A0 is equivalent -o. 

JTIST C MOVE I A,SRRCCD 
RET] 
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•CALLRET' may be used to call a subroutine and 
return immediately thereafter. It is an 
abbreviation for 

CALL SUBR 
RET 
or 

CALL SUBR 

RET 
RETSKP 

Mote that CALLRET is not guaranteed to be a single 

instruction; therefore it may not be skipped over. The 

other returns above are guaranteed to be single 
instructions. 

These mnemonics are used to emphasize the FUNCTION being 
performed (calling, returning) rather than the mechanics of 
the function (pushing, jumping, etc.). Also, these 
mnemonics could continue to be used even if a more general 
calling standard were adopted at some time in the future. 

Return may also be effected by transferring control to the 
global tag R or RSKP, e.g. 

JUMPS A,R /equivalent to JUMPS A,[RST] 

JUMPN A, RSKP /equivalent to JUMPM A, [RETSKP] 

The general temporaries shall be used for passing arguments 
to subroutines and returning values. AC1 shall be used for 
a single argument routine, ACs 1 and 2 for a two-argument 
routine, etc. 

A routine defined to return caller +2 (skip) on success and 
calier +1 (noskip) on failure is acceptable. Returns 
greater than caller +2 are not permitted. 
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AC DEFINITIONS 

with she AC us. « n ^ 6i |«, a =" a i ne „J e l sac nags, and 
each group ara consecutive. 

: - ? 10 - pi 

' 1 - Tl 11 - " 

2 - T2 12 - P3 

I".?! 13- P4 

4 - T4 14 - PS 

5 - Ql 15 - P6 

. fi - Q2 16 " <=X 

7 - Q3 17 - P 

The programmer should^assume that each |^f 4^ ut C ^ at: ? ^,e 
is in ascending order, a *3* ,^ h -« a * Explicit numeric 
specific assignment of numbers "*, ^"f^f fc m be used. 
offsets from AC symools (e.g. *-£ l ^ sn ° qiv, ■ JTFO) 

Instructions which use more than one «c <"^ athlir ACU) 

must be given an AC °P"f*e crous" £.= • T3 (and 
implicitly affected are in the same <3"£j^ 3 ^ noC bacause 
T4) is OK for I3IV because T3+1-T-, auc ^ J 

Q3*l«??. 

-i.- m««iH«r to save and 

There are several facilities in the ? mon = c to ^ |U of 

•automatical!'/ restore AC*, -ac.no. *..• . . .. ._ .^ 




need :sr 

returns. Use o = r^""* "£**;;:;;" a ;~ ^its of routines 
matching PUSH/POP pair* at the entry at -x i. unmat =H e d 

and eliminates the °«?V? S2«« !-•• 
PUSH or POP. The available macros a.-. 

SAVEQ - saves ACS Q1-Q3 
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SAVEP - saves ACs P1-P6 

SAVEPQ - saves ACs Q1-Q3 and PI-PS . 

SAVET - saves ACs T1-T4 

Defining a different mnemonic for a preserved AC may be of 
hoi U , e / n t 5 e AC i S USed for a specific function by a large 
™?».? °! 8 * However, it offers the possibility If 
confusion because two different symbols may refer tb the 

nVZ* JS !f b f' C ? 0W ?* t t0 the P"*rammer. In smaller programs, 

an3 » 0f „? , £ tt ? ln /S ? an be res1 =ri«=ted to specific functions 

m2n^., gl s bal deflnition is appropriate. A timesharing 

po°ss^i r e d h °ed W !^d lls. t0 ° l * W t0 — ^, all of th2 

is er mfSr' l" h tZJ, S E eCl£i ? • f ? n f ^on-oriented AC definition 
,,L "I i i" f * U be «Plicitly decided which' modules shall 
^r ^! ?r flni ! l 2 n ' Within theSe ^ules, the usual name 

nlLZ !„ ^7S" be ?Urged So that thers ls no Possibilitv of 
using uwo different symbols for the same AC. 1 *"» - 



Only preserved ACs nay be used for special definitions. 

d!fi?!?*£?« ?° J Ub J°yf ln ? 3 m ^ y be P ass ^ in functionally 
defined ACs in the following cases s 



1. On an intra-module call where the contents of the 
AC are appropriate to its function definition. 

2. On an inter-module call where- the- same, definition 
exists in both modules and the AC is; being aged-far 
its intended function. ■ 
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.SSi'5- a^.ctficNn.T.Iac.d^c cha action which the AC 
is .par forming. 

Th. procadur.^oc declaring a iuncticnally dafinad AC la: 
oetm none , oldac 

TM. «.t b. don. at th. b-lnnln, o£ an •««* l ]k t «£ £ 
d.ttn- ««« «» e £. T4ular" =r sarv,d a "ca, and thl. 
Snrontc CHl'S;. P«|«d an5 g ch. r8 ,oc. anavailabl. Cor usa in 

the current assembly. 




available. 

SUBROUTINE DOCUMENTATION 



ion of 



The 'o^owinc is a suggested So pat for dojomentin 
ine -o--«»i" , s , Tcvfl'nr subroutine. A de&crip>- 

calling sequence of a *S^S or suoro ut £"* ^ of ever/ 

this sort should appear at the oeg-nn-ng 
subroutine, no matter how short. 

;name of subroutine - function of subroutine, etc. 
- Tl/ description of fiir3t argument 
TV description of second argument 

CALL NAME or JSYSNAME 
RETURN +1: conditions giving this return/ 
Tl/ s value(s) returned ,*„„- 

RETURN *2: 'Conditions and values as abova. 



-..♦.» •• * inv should be documented as the 
a arguments, .-any, snou-- « * , , , a3 ghown . 

ntents of .*«?""" SfuLd when available; 
NS^. mnemonics should be usee wn-n 



Th 

CO 

MONS 

a.g. at JSYS entry points 
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The actual i 
shown. Thi 
internal sub 
in the case 

The return (s 
or "NEVER" 
appropriate; 
does not 
described in 



'CALL subname" in 



nstruction to do """the ' cafll 
s will be 
routines , 
of,,?».JSYS' 



should be 
the case of 



an$ the s4.ngle-word JSYS name 

.ert'fry :p'o in' t:. r -"■'■' ' u '~ - sr /:■ ' 

) should ; be noted "as ' VhVwh; ' ^ALWAYS" 

may be used as the condition where 

the +2 return need not be shown if it 

exist; , , values , returned . should ,.be 

the same form^as ^argunfentsv* '• s?: * ' 



Examples : 



1,v. 



SIN -COMPUTES SINE Of - AN -ANGLE- *»*- ■•■■ 
Tl/ ANGLE IN RADIANS; -FLOATING 'POINT;' •'•■'•-*• i i -w-i 
CALL SIN '-: , ~ v^cr... :■■.!•:-:.':; i> 

RETURN +1: FAILURE, UNFORMALIZED NUMBER OR OUT OF 
RANGE 
; RETURN +2: SUCCESS, Tl/ VALUE 1 ,'; FLOATING sPCXNT >• 



SIN: : 



i '• 



GJINF - GET JOB INFORMATION JSYS?.," ,: • 
GJINF 
RETURN +1: ALWAYS, 
Tl/ LOGGED-IN DIRECTORY ..NUMBER 5 ■■; 
T2/ CONNECTED DIRECTORY -NUMBER - - . : 5 -^ 
T3/ JOB NUMBER ■ -i. — 

T4/ TERMINAL NUMBER OR -I IF QETACJEQ., 

.GJINF: : .. 



MULTI-LINE LITERALS ' ' \ f "' 

The use of multi-line literals is ; encouraged ,, as a- technique 
for making code more readable' and .easier." to,-. 'ffilclow. The 
following additional rules apply: 
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ii .'. , , '-'.^ 

1. The opening bracket for a multi-line literal should 
■• occur ;ia -the -laaaition -that the first character of 

the address field, .,.*w«.yld : have appeared ic the 
instruction had an ^ordinary address, e.g. 

SKIPGE F00 

2. The € ; i¥st -and- 5 all -following instructions within the 
literal shall begin at the second tabstop, e.g. 

"" *'\ i-JHST f r -W3VE -A,MUMSt£ ( .'COMMENT 

, r, : -. ■. t - '-. t o p .: . JRST F-I3 f " ■ ' jCOMMEHT 

■-'-' '"-'The* tab -between the open bracket and the first 
opcode may be omitted if the line position is 
already at or beyond the second tab stop, e.g. 

JUMPGE A, [MOVE A, MUMBLE 

3. The closing bracket shall fallow the last field of 
the last t instruction .(as above), and shall be 
before "the ■■comment .on- the _/S ante line. 

4. Nesting" of -aulti-lihe' literals to a depth greater 
: ' '"' thjln , ' 'brta; . ..i*"'.*' discouraged ■ because of awkward 

.ffbrmatting/ problems... '"".., 

5. Tags may not appear in multi-line literals. 

6. No hard and fast ffulas can be given as to when to 
use or not use multi-line literals. However, a 
literal longer than about 13 lines becomes 
suspect. 

7. Use of ".+1" is legal in a literal to return to 
the main sequence. 
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CONVENTIONS'* 



• •■*•'■ * '••. .'';-■ :v::.r ;,'.";:«■,;£. : ; ~ ; 

In general, jumps shoul4"be: -ta> stsgss '-fitfrwa'rd "('.dawns the page) 
from the point of "'branch^ except if or skaa&s.;. Tops of loops 
should be identified by" . edahfi«i*t..<- .Is* -.1..;: r„ :.-;.- «= ;; ■ 

•3 . s , , •■ . : 
The expressions ".+1" and ".-1" are the only lasgal uses of 
"." (this location). All other potential uses should be 
avoided in favor of an; expilckiUy;d#£4n-.ftd--*&ag»> ., .■<>-■- 

>S, <■•■ "' '* •■ t , ■-, ,- I 1' .• . f ..... « '■ ? 

"Global 1 ! jumps shouid"*be avo, .t*«*>,,*l together .:*£ higher-level 
languages do not', ^permit them E":a^id\;*£th "good reason. The 
only exceptions are jumps to well defined and published exit 
sequences, e.g. ,,R-, RSgP *£see,. ,,§.ub ircuijine ^-conventions, 

above) . • - *..»• ."- : •■-..• ,- .■■ . „, .„.,.,.,.,,*, 



NUMBERS 



, ; ' M ; I M 



'«. *.< 



;>s 



there .should -be. 



a literal 



.., no . occasion ., , to . .use 
in-line code". ' All' parameters, bTtf'def initions, 



In general, 

number in 

CONC/CONI codes, etc. should rbe., defined . .ranemoniQally at 

appropriate places.;,. '..'. tfe", ..Is, ;Cmuc?h'"'"e||tar' " „to;^ err in the 

direction of too little use" e'f "„ mnemgn|c'^„„raj^h*e;'r than too 

much? therefore, when in ''''the"" '"'Slightest "doubt, define a 

mnemonic. 
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>. K;rr, J.f- 5 T. * it.jq h.4W R 4**rV 3'.-. •.;*'/!' 
:<fe£V5NG:E¥nM! ^PS^IS<?f S: WO|tD , ...^ _ . ., 

Much of the oresent T0PS23 coda was written before the 
existance of* this standard and therefpr*. does not conform uo 
it. A great deal of systematic editing" has already been 
•tJonar-td - imfeoye conformance,, bjifc. ,.pbvious irregularities 
•e«-ist.'-- In fetter al*» new,. v co^e, be tag , added should «n£orm 
.-exactly;, to- fcfeisn standard even if.-being integrated; with old 
,oode-.;,: The ;foilflw£ng, are- some specific x problems wnich may 
■aris«^and:ithe^racb«ffle©4.edt so lAit-ijOTts^. . - s . ; .,- ; > 

r' :i £ t? "i t ^ ^5 " t i?" *i.™ *- " '■ ' '*; - ■* '■'■■ ■ * C J" f-u 

1. AC Mnemonics 

Some code uses absolute numeric ACs. If new code is being 
integrated into a sequence which uses numeric ACs, it is 
desirable that the existing code be edited to use the 
standard mnemonics, particularly for the .preserved ACs. 1- 
the orogrammer cannot take the time to do that, then tue 
mnemonics T1-T4 should be used for ACs 1-4, and other ACs 
should be referenced in the same way as is done by tne 
existing code. 

Some code uses mnemonics A,3,C.,D for the temporary ACs. 
These same mnemonics should be used for new code integrate 
into this existing code, or all references can be edited to 
use the standard mnemonics. 

You may write some code using the standard mnemonics for 
cresarved ACs and then discover that the module into .which 
you wish to put this coda has redefined some^of these ACs. 
The solution* is one or a combination of the following: 

1. Move the new coda to a module which does not 
redefine the preserved ACs. 

2. Use different preserved ACs — ones which have not 
been redefined. (Note it is not acceptable to use 
an AC with a special definition for other than its 
special purpose.) 

Claarlv, code which needs some of the special definitions 
must be olaced in a module which has these ACs defines and 
must therefore use only the other preserved ACs. 
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Note that a value which usually resides in a special AC need 
not ALWAYS reside, there... For example, if code in JSYSF 
needs to call a routine tn'P&GtM^nd pass a JFN index as an 
argument, the JFN should„be„ loaded into T1-T4- for the call 
since PAGEM does not have JF^'aeilnld" "Jrid danh-6-t W accept an 
argument in it. 

■':'■■■ . ' ""■•' "■,-■■" > fc v. rssv: ;•*. 

..... Stack Handling:; -""' ■** «•■-* >*i^"-'£ 

Use of the seve'rai"f "stac^' vB^tiabfe^ facilities"' defined..'- *.fn 
MACSYM is recommended.. r'Spfee ciiMp -code ■' -uses ee spite it PUSH ;*j*d 
POP ind references ^'f-'^thre 1 Wrt» -"^P? 9* haw-tear^ an:d„vwh*n 
anything more than --"tH^i&i - fidtti«lfea«4dti«inofct ?bS made- .-to 
such code, it is most s^r8hgiy-**c^tt*etiiia*d:>*haftr.thfereo«S.e .! ;M9 
edited to use STKVAR or THVAR. Failing that, references 
must be consistent with the existing code. 

4 "if 3Slt*f.';.'' DA ,. * 
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